Packages for building apps on Tassyir. Merchants install these apps. An app calls the Tassyir Admin API, receives signed webhooks, and shows pages inside the Tassyir dashboard. It runs on the developer's own server or on Tassyir Hosting. Either way it uses the same manifest, API and events.
Docs: developers.tassyir.io: the guides, the Admin API reference, every error code and each package's reference.
Status: in development. This repo has its workspace, CI and release
pipeline (AP-K1.1). On npm since 0.1.0: @tassyir/app-manifest (AP-K1.2),
@tassyir/app (AP-K1.3), @tassyir/app-bridge (AP-K1.4), the tassyir CLI
(AP-K1.6) and create-tassyir-app (AP-K1.7). @tassyir/dev-mcp (AP-K1.8)
has its first release, 0.1.0, from the Version Packages PR of 2026-10-15.
@tassyir/ui (AP-K1.5) awaits its first release, 0.1.0: the owner's npm
stub and trusted publisher come first. So does @tassyir/storefront-blocks
(AP-K2.2), the first package of the marketplace phase. Each package's CHANGELOG says what
each version changed. The other packages arrive one ticket at a time.
Packages are published to the public npm registry under the @tassyir scope.
Each scoped package is also published, same version and same tarball, to
GitHub Packages, for Tassyir's own repositories. See
docs/RELEASING.md.
Each package's README below is also its page on the docs site,
https://developers.tassyir.io/packages/<folder>.
packages/app-manifest (AP-K1.2). The schema and
validator for tassyir.app.toml, the app manifest (v1, API version
2026-10). Give it the parsed manifest. It returns either the normalised
manifest or every error at once. Each error carries a stable code, the path
of the field, a message, and a one-sentence fix. The package ships the
published JSON Schema and the vocabulary it validates against (API versions,
scopes, webhook topics). It is the Tassyir API's own validator, so the CLI and
the server agree; docs/APP_MANIFEST.md says how that
is checked. Ships as ESM and CommonJS.
packages/app (AP-K1.3). The server side of an app. No
runtime dependency: it runs on Node 22 and on Workers-like runtimes. It
provides:
-
token exchange (ID token, install code) and refresh, with a store you provide and a lock so that only one refresh runs at a time;
-
verification of the ID token that the dashboard hands to an embedded page (Ed25519, keys from the JWKS);
-
webhook verification: Standard Webhooks headers and Ed25519
v1asignatures, checked against Tassyir's published keys, then the envelope's app and installation; -
a typed Admin API client (
https://api.tassyir.io/apps/2026-10/), generated from the API's OpenAPI 3.1 document, with typed errors, opt-in retries, idempotency keys and pagination. -
for apps on Tassyir Hosting:
readHostedProps(ctx)(the typedctx.props: installation, viewer,STORAGE,TASSYIR),hostedAdmin(props)(the same client, sent throughctx.props.TASSYIRwith no token) andverifyHostedWebhook(a delivery's signature verified with Tassyir's keys read throughctx.props.TASSYIR); -
verifyProxyRequestfor the app proxy (a store's/apps/<handle>/…requests forwarded to the app, signed with Tassyir's keys; AP-K2.3, built to the contract before the proxy opens).
packages/app-bridge (AP-K1.4). The embedded page's
side of the dashboard bridge. An app page runs inside the Tassyir dashboard
and talks to it through postMessage, to the dashboard's exact origin only.
With this package it can get an ID token, show toasts and modals, use the save
bar and title bar, navigate, pick products, collections or customers, and
follow locale, direction (RTL or LTR) and theme changes. Every refusal is a
typed error with a stable code and a fix. The dashboard never sends the page a
Tassyir credential: the ID token, verified on the app's server with
@tassyir/app, is the only proof of who is looking. Browser only, ESM only,
no runtime dependency. @tassyir/app-bridge/react adds React bindings (a
provider and hooks; React an optional peer dependency).
packages/ui (AP-K1.5). Web components that make an app's
page look like the Tassyir dashboard it runs in: the dashboard's design
tokens (colours, type, spacing, radii, light and dark) and fifteen custom
elements built from them: button, link, text field, select, checkbox, radio
group, card, page header, table, status pill, banner, empty state, skeleton
and spinner. Every element works right to left and left to right, light and
dark, on a phone and on a computer; one helper follows App Bridge's
language, direction and theme. The form controls submit with a native
<form>. Modals, toasts, pickers and the save bar are App Bridge calls, not
elements. Custom elements with no runtime dependency, so they work in any
framework or none. Browser only, ESM only, about 13.5 kB gzipped; no
analytics, no storage, no network.
packages/cli (AP-K1.6). The developer CLI. tassyir login
signs in with a code you approve in the dashboard (the OAuth device grant)
and keeps a developer token that works on the developer API only, in the OS
keychain when one answers, otherwise in a file only you can read; it is never
printed. Then: app init (the starter), app create, app list, validate
(offline, the API's own validator), deploy (the manifest as a new version;
for an app on Tassyir Hosting, the bundle built with esbuild, checked by the
API's rules before the upload, and its scan followed to the verdict, AP-K1.11),
app version (one version and its scan's findings),
secrets create | rotate | revoke (a secret is shown once, or written to
.env only when asked), store create | list (seeded dev stores), and
webhook trigger | deliveries | replay. For the marketplace (AP-K2.3):
validate and deploy check storefront blocks' files with
@tassyir/storefront-blocks (and deploy uploads them), block preview
renders one with sample data, listing pull | push keeps the draft listing in
a file, submit sends the app to review and follows its checklist
(--checks-only runs it alone), and submissions shows the reviews. dev
prints the checklist for now; logs --tail waits for Tassyir Hosting.
Every command prints --json, every error has a stable code and a fix,
and the exit codes are documented. Its developer-API client is typed from the
API's OpenAPI document. Published to npm only.
packages/create-tassyir-app (AP-K1.7). The
starter: npm create tassyir-app@latest my-app. Two templates. external
(the default) is an app on your own server: Node 22 and Hono, the embedded page
on @tassyir/app-bridge and @tassyir/ui, token exchange and the Admin API through
@tassyir/app with an encrypted file token store, a webhook endpoint that
verifies the raw body, and a tassyir.app.toml that @tassyir/app-manifest
validates. It comes with an AGENTS.md, a CLAUDE.md and a tassyir-app
Claude Code skill that explains the contract, and with specs against a fake
Tassyir API. The project's README walks the real path: the developer console,
a dev store, an https tunnel, the install. hosted (--template hosted) is
an app on Tassyir Hosting: a Cloudflare Worker (Hono) that reads its
installation, STORAGE and the Admin API from ctx.props, a React page on
@tassyir/app-bridge/react and @tassyir/ui, specs in workerd, and
npm run deploy (tassyir deploy). CI generates a project of each template
with the packed CLI, then installs, typechecks, tests and builds it, starts
the external one and runs the hosted one's deploy checks
(npm run check:template). Published to npm only.
packages/dev-mcp (AP-K1.8). An MCP server, over stdio,
for the AI coding agent that builds a Tassyir app:
claude mcp add tassyir -- npx -y @tassyir/dev-mcp. Offline, from the guides
and the OpenAPI documents it ships with (the Admin API's and the developer
API's): search_docs, fetch_doc,
get_api_operation, get_event_schema, and validate_manifest (the API's
own validator). scaffold writes a new app from create-tassyir-app.
trigger_test_webhook, seed_dev_store and list_dev_stores call the
developer API with the sign-in of tassyir login, whose token never appears
in an answer. validate_block checks a storefront block offline, and
run_review_checks runs the marketplace review's checklist as a dry run
(AP-K2.3). tail_logs is listed and answers that it is not available yet
(Tassyir Hosting's logs). Every tool has a JSON Schema input and output, every answer is at
most 8 KB, and every refusal of a well-formed call has a code and a fix.
In Claude Code, the tassyir plugin bundles the server with the starter's
tassyir-app skill (the app contract):
/plugin marketplace add tassyir/apps-sdk
/plugin install tassyir@tassyir
The marketplace is .claude-plugin/marketplace.json
and the plugin plugins/tassyir. Its server is pinned to
the current @tassyir/dev-mcp release and its skill is the template's, both
kept in step by npm run plugin:sync and a spec.
packages/storefront-blocks (AP-K2.2). The
language of storefront blocks, the HTML an app adds to a merchant's store
pages (not live yet: blocks open with the marketplace): a Liquid subset with
its own small parser, a validator whose every error has a code, a line, a
column and a fix, and a renderer that escapes every output, counts its
work in steps (never a clock) and rebuilds the HTML from an allowlist. The
Tassyir API checks block uploads with it, the store builder and the
storefront render with it, and the CLI previews with it. No dependency; the
same bytes in Node and browsers, proved by a fuzzed corpus of planted
sanitiser bypasses (npm run browser-parity -w @tassyir/storefront-blocks
runs it in Chrome and JavaScriptCore). Ships as ESM and CommonJS, to npm and
GitHub Packages.
developers.tassyir.io/guides, written in docs/guides (AP-B1.17): one guide per topic, from getting started to webhooks, the Admin API's conventions, every resource, dev stores and compliance, plus an error reference generated from the OpenAPI document. Every code sample is typechecked against the packed packages.
site (AP-K1.9): the developer docs site,
developers.tassyir.io, on Mintlify. It
publishes the guides, the Admin and developer API references from the OpenAPI documents, one
page per error code at its problem type URL, and each package's README,
all generated from this repo (npm run docs:sync, kept in step by a spec),
with llms.txt,
llms-full.txt, a Markdown
copy of every page (its address plus .md) and an MCP server
(https://developers.tassyir.io/mcp).
Read AGENTS.md first. It covers setup, commands, the module format, how to add a package, and the rules of a public repo. You need Node 22, then:
npm cinpm run verify