pointiv-extension-sdk

Python SDK for Pointiv WASM extensions.

Install

pip install pointiv-extension-sdk

Setup

extism-py requires @extism.import_fn host bindings in the compiled entry file. Declare them in host_bindings.py, wire the SDK with bind, then build a merged entry:

# host_bindings.py
import extism
from pointiv_extension_sdk import bind

@extism.import_fn("extism:host", "pointiv_storage_read")
def pointiv_storage_read(key: str) -> str: pass

@extism.import_fn("extism:host", "pointiv_storage_write")
def pointiv_storage_write(key: str, value: str): pass

@extism.import_fn("extism:host", "pointiv_storage_delete")
def pointiv_storage_delete(key: str): pass

bind.storage_hosts(pointiv_storage_read, pointiv_storage_write, pointiv_storage_delete)

cat host_bindings.py main.py > entry.py
extism-py entry.py -o extension.wasm

See the Python starter for a full example.

Build to WASM with extism-py, then set runtime: "wasm" and main: "extension.wasm" in pointiv-extension.json.

APIs

Calls without permission fail safely.

Python/WASM limitations

extism-py cannot call zero-argument host functions reliably. These APIs raise NotImplementedError in Python/WASM builds:

• storage.list()
• clipboard.read()

Use storage.read() / storage.write() / storage.delete() instead. Host functions use the extism:host namespace (Pointiv registers both extism:host and extism:host/user).

Tiles

Extensions can render a declarative tile widget beside the popup command bar. Declare a "tiles" block in pointiv-extension.json (requires "runtime": "wasm") and export render_tile from your entry file. render_tile is a plugin export decorated with @extism.plugin_fn, so the host-import shims wired through bind.py stay exactly as they are:

import json
import extism
from pointiv_extension_sdk import tile

@extism.plugin_fn
def render_tile():
    # input is {"now": "<RFC3339>"}: json.loads(extism.input_str())
    ui = tile.tile(
        "Todos",
        body=[
            tile.badge("2 open", tone="warn"),
            tile.row("Buy milk", actions=[tile.action("Done", "todo done 1")]),
        ],
        footer=[tile.action("Refresh", "todo list")],
    )
    tile.output_tile(ui)

"tiles": { "height": 2, "zone": "right", "order": 1 }

The host calls render_tile when the popup opens and after a tile action runs, with a 3 second budget and storage-only host access. Action commands run through your normal execute function. Iterate with the playground in Pointiv Settings, Tiles: paste tile JSON for instant validation and preview, or live-render an installed extension's tile. Full schema, limits, and the component catalog are in TILES.md in the Pointiv repo.

Manifest

{
  "name": "My Extension",
  "description": "What it does",
  "version": "1.0.0",
  "author": "your-name",
  "keywords": ["tag"],
  "runtime": "wasm",
  "main": "extension.wasm",
  "permissions": ["storage", "network", "google_calendar", "google_gmail"]
}

License

MIT