# Get an access token
Source: https://developers.tassyir.io/api-reference/admin/authentication/get-an-access-token

/openapi/openapi.2026-10.json post /apps/oauth/token
Three grants: the token exchange of an embedded page's ID token (an offline token, or an online one bound to the dashboard user), an install code, and a refresh token (rotated on every use; a spent one presented after 60 seconds revokes its whole family).

Client authentication is HTTP Basic only. Errors are OAuth's `{ error, error_description }`, not problem+json. Limits: 300 requests a minute per client id, 30 failed authentications a minute per IP (429 `slow_down`).



# ID-token public keys (JWKS)
Source: https://developers.tassyir.io/api-reference/admin/authentication/id-token-public-keys-jwks

/openapi/openapi.2026-10.json get /apps/.well-known/jwks.json
Verify the ID token your embedded page receives: pick the key by `kid`, require `alg: EdDSA`, `iss = https://api.tassyir.io/apps`, `aud = <your client_id>`, and `exp`/`nbf` with at most 30 s of clock skew.



# Webhook public keys
Source: https://developers.tassyir.io/api-reference/admin/authentication/webhook-public-keys

/openapi/openapi.2026-10.json get /apps/webhook-keys
Verify a delivery: the signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`; accept it when any `v1a,` signature verifies with any key here and the timestamp is within 5 minutes.



# Export a whole list
Source: https://developers.tassyir.io/api-reference/admin/bulk-exports/export-a-whole-list

/openapi/openapi.2026-10.json post /apps/2026-10/bulk/exports
Starts an export of every row the list route of `resource` returns (with these `filters`, the list's own), as one JSON Lines file: one resource per line, exactly as the list returns it, newest first. It runs in the background: read `GET /bulk/exports/{id}` or subscribe to `bulk/finished`; once `completed`, download the file from `url` (7 days). 1 export queued or running per installation, 5 asked for per business (every app together) in any hour. Send an `Idempotency-Key`: a retry then answers the same export.

The scope depends on the list exported: `orders` needs the `read_orders` scope (permission `orders:read`); `products` needs the `read_products` scope (permission `products:read`); `customers` needs the `read_customers` scope (permission `customers:read`).



# Get an export
Source: https://developers.tassyir.io/api-reference/admin/bulk-exports/get-an-export

/openapi/openapi.2026-10.json get /apps/2026-10/bulk/exports/{id}
Where it stands, and its download `url` once `completed`. Poll it at most every few seconds, or subscribe to `bulk/finished`.

The scope depends on the list exported: `orders` needs the `read_orders` scope (permission `orders:read`); `products` needs the `read_products` scope (permission `products:read`); `customers` needs the `read_customers` scope (permission `customers:read`).



# List the installation's exports
Source: https://developers.tassyir.io/api-reference/admin/bulk-exports/list-the-installations-exports

/openapi/openapi.2026-10.json get /apps/2026-10/bulk/exports
Newest first, kept 30 days. Only the lists whose read permission the caller holds; an online token sees only the exports its own user asked for.

The scope depends on the list exported: `orders` needs the `read_orders` scope (permission `orders:read`); `products` needs the `read_products` scope (permission `products:read`); `customers` needs the `read_customers` scope (permission `customers:read`).



# The business the app is installed on
Source: https://developers.tassyir.io/api-reference/admin/business/the-business-the-app-is-installed-on

/openapi/openapi.2026-10.json get /apps/2026-10/business
Every installation may read it, whatever its scopes: the id, name, currency, country and time zone, nothing else.

Every installation may call it, whatever its scopes.



# Change a collection's members
Source: https://developers.tassyir.io/api-reference/admin/collections/change-a-collections-members

/openapi/openapi.2026-10.json patch /apps/2026-10/collections/{id}/products
`add` picks products by hand (and lifts an exclusion); `remove` takes them out whatever put them there.

Needs the `write_products` scope (permission `categories:update`).



# Create a collection
Source: https://developers.tassyir.io/api-reference/admin/collections/create-a-collection

/openapi/openapi.2026-10.json post /apps/2026-10/collections
Needs the `write_products` scope (permission `categories:create`).



# Delete a collection
Source: https://developers.tassyir.io/api-reference/admin/collections/delete-a-collection

/openapi/openapi.2026-10.json delete /apps/2026-10/collections/{id}
Its products leave it (they stay in the catalogue); its subcollections move up one level.

Needs the `write_products` scope (permission `categories:delete`).



# Get a collection
Source: https://developers.tassyir.io/api-reference/admin/collections/get-a-collection

/openapi/openapi.2026-10.json get /apps/2026-10/collections/{id}
Needs the `read_products` scope (permission `categories:read`).



# List collections
Source: https://developers.tassyir.io/api-reference/admin/collections/list-collections

/openapi/openapi.2026-10.json get /apps/2026-10/collections
Needs the `read_products` scope (permission `categories:read`).



# Update a collection
Source: https://developers.tassyir.io/api-reference/admin/collections/update-a-collection

/openapi/openapi.2026-10.json patch /apps/2026-10/collections/{id}
Needs the `write_products` scope (permission `categories:update`).



# Get a customer
Source: https://developers.tassyir.io/api-reference/admin/customers/get-a-customer

/openapi/openapi.2026-10.json get /apps/2026-10/customers/{id}
Needs the `read_customers` scope (permission `customers:read`).



# List customers
Source: https://developers.tassyir.io/api-reference/admin/customers/list-customers

/openapi/openapi.2026-10.json get /apps/2026-10/customers
The buyers with a counted order in the installation's stores. `name` and `phone` only with `read_customer_contact`.

Needs the `read_customers` scope (permission `customers:read`).



# Delete a value
Source: https://developers.tassyir.io/api-reference/admin/data/delete-a-value

/openapi/openapi.2026-10.json delete /apps/2026-10/data/{ownerType}/{ownerId}/{key}
Works for a key the version no longer declares too: that is how an app frees room after dropping a key.

The scope depends on the owner type: `business` needs none; `store` needs the `read_stores` scope (permission `stores:read`); `product` needs the `read_products` scope (permission `products:read`); `order` needs the `read_orders` scope (permission `orders:read`); `customer` needs the `read_customers` scope (permission `customers:read`).



# Get a value
Source: https://developers.tassyir.io/api-reference/admin/data/get-a-value

/openapi/openapi.2026-10.json get /apps/2026-10/data/{ownerType}/{ownerId}/{key}
Read whatever the manifest says now: a key the installation's version no longer declares is still read (`declared: false`).

The scope depends on the owner type: `business` needs none; `store` needs the `read_stores` scope (permission `stores:read`); `product` needs the `read_products` scope (permission `products:read`); `order` needs the `read_orders` scope (permission `orders:read`); `customer` needs the `read_customers` scope (permission `customers:read`).



# List the app's values
Source: https://developers.tassyir.io/api-reference/admin/data/list-the-apps-values

/openapi/openapi.2026-10.json get /apps/2026-10/data
The values this installation keeps, newest first, of the owner types its scopes may read. A value whose owner it can no longer read is left out, so a page can hold fewer than `limit` values while `nextCursor` is set: keep reading until it is null. `ownerId` needs `ownerType`.

The scope depends on the owner type: `business` needs none; `store` needs the `read_stores` scope (permission `stores:read`); `product` needs the `read_products` scope (permission `products:read`); `order` needs the `read_orders` scope (permission `orders:read`); `customer` needs the `read_customers` scope (permission `customers:read`).



# Write a value
Source: https://developers.tassyir.io/api-reference/admin/data/write-a-value

/openapi/openapi.2026-10.json put /apps/2026-10/data/{ownerType}/{ownerId}/{key}
Writes the whole value. The key must be declared for the owner type by the installation's version; the value must be of the declared type and at most 16,384 bytes of compact JSON; `visibility` comes from the declaration. An installation holds at most 50,000 values: past that a NEW key is refused, an existing one is still rewritten.

The scope depends on the owner type: `business` needs none; `store` needs the `read_stores` scope (permission `stores:read`); `product` needs the `read_products` scope (permission `products:read`); `order` needs the `read_orders` scope (permission `orders:read`); `customer` needs the `read_customers` scope (permission `customers:read`).



# Get a delivery agent
Source: https://developers.tassyir.io/api-reference/admin/delivery/get-a-delivery-agent

/openapi/openapi.2026-10.json get /apps/2026-10/delivery-agents/{id}
Needs the `read_delivery` scope (permission `delivery-agents:read`).



# Get a delivery fee group
Source: https://developers.tassyir.io/api-reference/admin/delivery/get-a-delivery-fee-group

/openapi/openapi.2026-10.json get /apps/2026-10/delivery-fee-groups/{id}
With its fees, one per wilaya.

Needs the `read_delivery` scope (permission `delivery-fees:read`).



# List delivery agents
Source: https://developers.tassyir.io/api-reference/admin/delivery/list-delivery-agents

/openapi/openapi.2026-10.json get /apps/2026-10/delivery-agents
The carriers and private couriers the business ships with. Credentials are never returned.

Needs the `read_delivery` scope (permission `delivery-agents:read`).



# List delivery fee groups
Source: https://developers.tassyir.io/api-reference/admin/delivery/list-delivery-fee-groups

/openapi/openapi.2026-10.json get /apps/2026-10/delivery-fee-groups
Every group at once, without its fees (read one group for them).

Needs the `read_delivery` scope (permission `delivery-fees:read`).



# Upload an image from an address
Source: https://developers.tassyir.io/api-reference/admin/images/upload-an-image-from-an-address

/openapi/openapi.2026-10.json post /apps/2026-10/images
Downloads the image at `url` and stores it on the Tassyir CDN; the answer's `url` is what product and collection writes accept. https on port 443 only, a public host name; a JPEG, PNG, GIF or WebP image (read from its bytes, never its name or `Content-Type`; SVG refused) of at most 10,000,000 bytes, 12,000 pixels on a side and 100 megapixels. Quota: 1,000 a UTC day per installation, 2,000 per business (every app together; a dev store 100 and 200), 30 a minute per installation. Send an `Idempotency-Key`: a retry then answers the same image without uploading it again.

Needs the `write_products` scope (permission `products:create`).



# Correct a stock count
Source: https://developers.tassyir.io/api-reference/admin/inventory/correct-a-stock-count

/openapi/openapi.2026-10.json post /apps/2026-10/inventory-levels/{id}/adjust
The dashboard's "correct the count, and say why". Never below zero at the location.

Needs the `write_inventory` scope (permission `inventory:update`).



# Get a stock level
Source: https://developers.tassyir.io/api-reference/admin/inventory/get-a-stock-level

/openapi/openapi.2026-10.json get /apps/2026-10/inventory-levels/{id}
Needs the `read_inventory` scope (permission `inventory:read`).



# List stock levels
Source: https://developers.tassyir.io/api-reference/admin/inventory/list-stock-levels

/openapi/openapi.2026-10.json get /apps/2026-10/inventory-levels
One per tracked variant. `unitCost` only for a caller holding `read_costs`.

Needs the `read_inventory` scope (permission `inventory:read`).



# Add a code to an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/add-a-code-to-an-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/codes
One code for a `code` offer. Codes are unique across the business (any case, disabled ones included): 409 `OFFER_CODE_TAKEN`. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Add up to 250 codes to an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/add-up-to-250-codes-to-an-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/codes/bulk
One call, at most 250 codes (one per influencer, say). Partial by design: a code with a bad format, a repeat inside the request or one the business already has is reported for THAT entry in `results` and the others are created; the call is 200 whatever the mix. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Create an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/create-an-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers
Always a DRAFT, owned by the calling installation: publish it with `POST /offers/{id}/publish`. The body is the dashboard's create body (`kind`, `method`, `title`, `label`, `config`, `combinesWith`, `eligibility`, limits, dates, `targets`, and up to 250 `codes` for a `code` offer) with the store in the body: `config` is the rule exactly as the Offers page stores it, not the shape `GET /offers` answers. Validated by the same rules as the dashboard (`400 OFFER_INVALID` lists `errors` with a `field` and a `code` each). An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:create`).



# Delete or archive an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/delete-or-archive-an-offer

/openapi/openapi.2026-10.json delete /apps/2026-10/offers/{id}
An offer nobody ever redeemed is deleted with its codes and targets (`deleted: true`, `offers/deleted`). One with any redemption keeps its history and is archived instead (`archived: true`, status `ended`, `offers/updated`); archiving again changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:delete`).



# Disable a code
Source: https://developers.tassyir.io/api-reference/admin/offers/disable-a-code

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/codes/{codeId}/disable
A disabled code stops applying; its history and its spelling are kept (it cannot be added again). Disabling a disabled code changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Enable a disabled code
Source: https://developers.tassyir.io/api-reference/admin/offers/enable-a-disabled-code

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/codes/{codeId}/enable
Enabling an enabled code changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Get an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/get-an-offer

/openapi/openapi.2026-10.json get /apps/2026-10/offers/{id}
Needs the `read_offers` scope (permission `offers:read`).



# List an offer's codes
Source: https://developers.tassyir.io/api-reference/admin/offers/list-an-offers-codes

/openapi/openapi.2026-10.json get /apps/2026-10/offers/{id}/codes
Newest first, disabled codes included. Only the owner reads them: An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `read_offers` scope (permission `offers:read`).



# List an offer's redemptions
Source: https://developers.tassyir.io/api-reference/admin/offers/list-an-offers-redemptions

/openapi/openapi.2026-10.json get /apps/2026-10/offers/{id}/redemptions
Each use of the offer on an order, newest first: the order id, the code and the amount it took off. Never the buyer: no name, no phone, no phone key. Only the owner reads them: An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `read_offers` scope (permission `offers:read`).



# List offers
Source: https://developers.tassyir.io/api-reference/admin/offers/list-offers

/openapi/openapi.2026-10.json get /apps/2026-10/offers
The merchant's per-store pricing offers (quantity offers, free delivery, product discounts), newest first, drafts included. A store-limited installation reads the offers of its stores. Codes are not exposed (their count is), and neither is any usage: never a buyer.

Needs the `read_offers` scope (permission `offers:read`).



# Pause an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/pause-an-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/pause
Stops a live offer pricing orders; resume it to start again. Pausing a paused offer changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Publish an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/publish-an-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/publish
Puts a draft live (from its start date). An incomplete offer is 400 `OFFER_INVALID`; past the plan's `active_offers` cap it is 403 `PLAN_LIMIT_REACHED` (the cap counts an app's offers like the merchant's). Publishing a published offer changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Resume a paused offer
Source: https://developers.tassyir.io/api-reference/admin/offers/resume-a-paused-offer

/openapi/openapi.2026-10.json post /apps/2026-10/offers/{id}/resume
Starts a paused offer again; the plan's `active_offers` cap applies. An ended offer is not resumed: move its end date instead. Resuming an offer that is not paused changes nothing. An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Update an offer
Source: https://developers.tassyir.io/api-reference/admin/offers/update-an-offer

/openapi/openapi.2026-10.json patch /apps/2026-10/offers/{id}
Changes the fields sent (`targets`, when sent, replaces the whole target set; `kind` and `method` never change). A live offer must stay publishable. The change applies to the offer as it is now unless `expectedVersion` is sent (the dashboard's compare-and-set, 409 `OFFER_VERSION_CONFLICT` with `currentVersion`). An app changes, and reads the codes and redemptions of, only the offers its own installation created (`ownerInstallationId` is set from the token when it creates one). A merchant's offer, or another app's, is 403 `OFFER_NOT_OWNED`; an offer the token cannot see (another business, a store outside the installation's stores) is 404.

Needs the `write_offers` scope (permission `offers:update`).



# Cancel an order
Source: https://developers.tassyir.io/api-reference/admin/orders/cancel-an-order

/openapi/openapi.2026-10.json post /apps/2026-10/orders/{id}/cancel
With one of `GET cancel-reasons` and a note when that reason asks for one. Recorded as cancelled by the app.

Needs the `write_orders` scope (permission `orders:cancel`).



# Comment on an order
Source: https://developers.tassyir.io/api-reference/admin/orders/comment-on-an-order

/openapi/openapi.2026-10.json post /apps/2026-10/orders/{id}/comments
Needs the `write_orders` scope (permission `orders:add-comment`).



# Confirm an order
Source: https://developers.tassyir.io/api-reference/admin/orders/confirm-an-order

/openapi/openapi.2026-10.json post /apps/2026-10/orders/{id}/confirm
Needs the `write_orders` scope (permission `orders:confirm`).



# Create an order
Source: https://developers.tassyir.io/api-reference/admin/orders/create-an-order

/openapi/openapi.2026-10.json post /apps/2026-10/orders
The dashboard's manual create: allowance admit, one distribution pass, `source = app:<handle>`. Past the plan's allowance the order is created WAITING (phones hidden, confirm and dispatch locked). `codes` (one offer code at most) prices the order with that code when the business has order pricing on; a code that does not apply is listed in `rejectedCodes` beside `data` and the order is still created. On a dev store, orders are capped per day: 429 `DEV_STORE_ORDER_LIMIT_REACHED` with `retryAfterSeconds`.

Needs the `write_orders` scope (permission `orders:create`).



# Get an order
Source: https://developers.tassyir.io/api-reference/admin/orders/get-an-order

/openapi/openapi.2026-10.json get /apps/2026-10/orders/{id}
Needs the `read_orders` scope (permission `orders:read`).



# List an order's comments
Source: https://developers.tassyir.io/api-reference/admin/orders/list-an-orders-comments

/openapi/openapi.2026-10.json get /apps/2026-10/orders/{id}/comments
Needs the `read_orders` scope (permission `orders:read`).



# List orders
Source: https://developers.tassyir.io/api-reference/admin/orders/list-orders

/openapi/openapi.2026-10.json get /apps/2026-10/orders
Every stage in one list, archived included, newest first. Never an undecided abandoned checkout nor an exchange-return row. Without `orders:read-all` (an online token of a member who sees only their own orders), only the orders assigned to that member.

Needs the `read_orders` scope (permission `orders:read`).



# Schedule a call-back
Source: https://developers.tassyir.io/api-reference/admin/orders/schedule-a-call-back

/openapi/openapi.2026-10.json post /apps/2026-10/orders/{id}/schedule
Needs the `write_orders` scope (permission `orders:schedule`).



# The merchant's cancel reasons
Source: https://developers.tassyir.io/api-reference/admin/orders/the-merchants-cancel-reasons

/openapi/openapi.2026-10.json get /apps/2026-10/cancel-reasons
The active reasons, in the merchant's order, all at once (`nextCursor` is always null).

Needs the `read_orders` scope (permission `orders:read`).



# Update an order
Source: https://developers.tassyir.io/api-reference/admin/orders/update-an-order

/openapi/openapi.2026-10.json patch /apps/2026-10/orders/{id}
The buyer, the delivery choice and the notes. Not the status (confirm, cancel and schedule have their own routes), not the items, prices, carrier or store.

Needs the `write_orders` scope (permission `orders:update`).



# Create a product
Source: https://developers.tassyir.io/api-reference/admin/products/create-a-product

/openapi/openapi.2026-10.json post /apps/2026-10/products
Images must already be on the Tassyir CDN; a description is checked (no scripts, frames, forms, handlers, fetching CSS).

Needs the `write_products` scope (permission `products:create`).



# Get a product
Source: https://developers.tassyir.io/api-reference/admin/products/get-a-product

/openapi/openapi.2026-10.json get /apps/2026-10/products/{id}
Needs the `read_products` scope (permission `products:read`).



# List products
Source: https://developers.tassyir.io/api-reference/admin/products/list-products

/openapi/openapi.2026-10.json get /apps/2026-10/products
Every product, active or not, newest first. A collection membership change does not move `updatedAt` (listen to `products/updated` for `collectionIds`).

Needs the `read_products` scope (permission `products:read`).



# Update a product
Source: https://developers.tassyir.io/api-reference/admin/products/update-a-product

/openapi/openapi.2026-10.json patch /apps/2026-10/products/{id}
`options` and `variants` are replace-all, together: every `id` sent must be one of this product's variants; a variant left out is removed.

Needs the `write_products` scope (permission `products:update`).



# Update one variant's fields
Source: https://developers.tassyir.io/api-reference/admin/products/update-one-variants-fields

/openapi/openapi.2026-10.json patch /apps/2026-10/products/{id}/variants/{variantId}
Only this variant is written; the others are sent back as they are. The default variant follows its product and is changed through it.

Needs the `write_products` scope (permission `products:update`).



# Get a store
Source: https://developers.tassyir.io/api-reference/admin/stores/get-a-store

/openapi/openapi.2026-10.json get /apps/2026-10/stores/{id}
Needs the `read_stores` scope (permission `stores:read`).



# List stores
Source: https://developers.tassyir.io/api-reference/admin/stores/list-stores

/openapi/openapi.2026-10.json get /apps/2026-10/stores
Needs the `read_stores` scope (permission `stores:read`).



# Abandoned checkoutscreated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/abandoned_checkoutscreated

/openapi/openapi.2026-10.json webhook abandoned_checkouts/created
An abandoned checkout was captured.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Appinstalled
Source: https://developers.tassyir.io/api-reference/admin/webhooks/appinstalled

/openapi/openapi.2026-10.json webhook app/installed
The app was installed on a business.

About the installation itself: sent to that installation only.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Appscopes updated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/appscopes_updated

/openapi/openapi.2026-10.json webhook app/scopes_updated
The merchant granted a new set of scopes.

About the installation itself: sent to that installation only.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Appuninstalled
Source: https://developers.tassyir.io/api-reference/admin/webhooks/appuninstalled

/openapi/openapi.2026-10.json webhook app/uninstalled
The app was uninstalled; its tokens are already revoked.

About the installation itself: sent to that installation only.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Bulkfinished
Source: https://developers.tassyir.io/api-reference/admin/webhooks/bulkfinished

/openapi/openapi.2026-10.json webhook bulk/finished
A bulk export this installation asked for finished: `completed` (download it from `url`) or `failed` (`errorCode`). Sent only to that installation.

About the installation itself: sent to that installation only.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Businessredact
Source: https://developers.tassyir.io/api-reference/admin/webhooks/businessredact

/openapi/openapi.2026-10.json webhook business/redact
Delete what you hold about this business: the app was uninstalled 48 h ago and Tassyir has deleted its app data.

A compliance topic: sent to that uninstalled installation only, when its version subscribes; never to another app.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Customersdata request
Source: https://developers.tassyir.io/api-reference/admin/webhooks/customersdata_request

/openapi/openapi.2026-10.json webhook customers/data_request
A buyer asked for the data held about them.

A compliance topic: every installation that subscribes receives it, whatever its scopes.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Customersredact
Source: https://developers.tassyir.io/api-reference/admin/webhooks/customersredact

/openapi/openapi.2026-10.json webhook customers/redact
Delete what you hold about this buyer.

A compliance topic: every installation that subscribes receives it, whatever its scopes.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Customersupdated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/customersupdated

/openapi/openapi.2026-10.json webhook customers/updated
A customer's record changed.

Sent to installations granted `read_customers` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Inventory levelsupdated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/inventory_levelsupdated

/openapi/openapi.2026-10.json webhook inventory_levels/updated
A variant's on-hand, in-transit or damaged stock changed.

Sent to installations granted `read_inventory` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Offerscreated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/offerscreated

/openapi/openapi.2026-10.json webhook offers/created
An offer was created (as a draft).

Sent to installations granted `read_offers` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Offersdeleted
Source: https://developers.tassyir.io/api-reference/admin/webhooks/offersdeleted

/openapi/openapi.2026-10.json webhook offers/deleted
An offer that was never redeemed was deleted; only its id remains.

Sent to installations granted `read_offers` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Offersupdated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/offersupdated

/openapi/openapi.2026-10.json webhook offers/updated
An offer changed (publishing, pausing, archiving, its dates, rules and codes included); `changed` names the fields.

Sent to installations granted `read_offers` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Orderscancelled
Source: https://developers.tassyir.io/api-reference/admin/webhooks/orderscancelled

/openapi/openapi.2026-10.json webhook orders/cancelled
An order was cancelled.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Ordersconfirmed
Source: https://developers.tassyir.io/api-reference/admin/webhooks/ordersconfirmed

/openapi/openapi.2026-10.json webhook orders/confirmed
An order was confirmed.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Orderscreated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/orderscreated

/openapi/openapi.2026-10.json webhook orders/created
A real order was created (never an abandoned checkout), after the order allowance decided it.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Ordersdelivered
Source: https://developers.tassyir.io/api-reference/admin/webhooks/ordersdelivered

/openapi/openapi.2026-10.json webhook orders/delivered
An order was delivered.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Ordersdispatched
Source: https://developers.tassyir.io/api-reference/admin/webhooks/ordersdispatched

/openapi/openapi.2026-10.json webhook orders/dispatched
An order was handed to a carrier.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Ordersreturned
Source: https://developers.tassyir.io/api-reference/admin/webhooks/ordersreturned

/openapi/openapi.2026-10.json webhook orders/returned
An order came back (its status does not change: `returned` is true).

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Ordersupdated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/ordersupdated

/openapi/openapi.2026-10.json webhook orders/updated
Any other change to a field an app can read; `changed` names the fields.

Sent to installations granted `read_orders` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Productscreated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/productscreated

/openapi/openapi.2026-10.json webhook products/created
A product was created.

Sent to installations granted `read_products` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Productsdeleted
Source: https://developers.tassyir.io/api-reference/admin/webhooks/productsdeleted

/openapi/openapi.2026-10.json webhook products/deleted
A product was deleted; only its ids remain.

Sent to installations granted `read_products` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Productsupdated
Source: https://developers.tassyir.io/api-reference/admin/webhooks/productsupdated

/openapi/openapi.2026-10.json webhook products/updated
A product changed (deactivation included: `active` turns false).

Sent to installations granted `read_products` whose version subscribes to the topic.

At least once, no ordering guarantee. `data` is read when the body is built (seconds after the event), masked for the installation.



# Accept the developer terms
Source: https://developers.tassyir.io/api-reference/developer/account/accept-the-developer-terms

/openapi/openapi.developer.json post /developer/terms
Records that you accepted the "Developer terms for free apps" version `2026-10` (the only one accepted today; read `terms.currentVersion` on your account). Needed before a listing submission; a new version asks again before your next one.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Change your developer account
Source: https://developers.tassyir.io/api-reference/developer/account/change-your-developer-account

/openapi/openapi.developer.json patch /developer/account
`websiteUrl: null` clears it; `null` is refused for the other two.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Get your developer account
Source: https://developers.tassyir.io/api-reference/developer/account/get-your-developer-account

/openapi/openapi.developer.json get /developer/account
Null when developer mode is off: not an error, the console asks this once to decide what to draw.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Turn developer mode on
Source: https://developers.tassyir.io/api-reference/developer/account/turn-developer-mode-on

/openapi/openapi.developer.json post /developer/account
Every field is optional: `displayName` defaults to your name (else the part of your email before `@`), `supportEmail` to your email. `displayName` follows the manifest's `name` rule (1-50 characters on one line).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Change an app
Source: https://developers.tassyir.io/api-reference/developer/apps/change-an-app

/openapi/openapi.developer.json patch /developer/apps/{appId}
Its names and `customBusinessId` (`null` clears it). The handle, client id, hosting mode and distribution never change. A LISTED app's name changes through its listing (`409 APP_NAME_LOCKED`).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Create an app
Source: https://developers.tassyir.io/api-reference/developer/apps/create-an-app

/openapi/openapi.developer.json post /developer/apps
It has no version and no secret yet. `handle` is permanent (the manifest's `handle` rule, unique on Tassyir); `clientId` is minted here and never changes. `hostingMode: tassyir` is refused while Tassyir Hosting is switched off or not open to your developer account; the mode follows the app's current version.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Get one of your apps
Source: https://developers.tassyir.io/api-reference/developer/apps/get-one-of-your-apps

/openapi/openapi.developer.json get /developer/apps/{appId}
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List your apps
Source: https://developers.tassyir.io/api-reference/developer/apps/list-your-apps

/openapi/openapi.developer.json get /developer/apps
Newest first, at most 50 (an account holds at most 50 apps).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Approve a CLI sign-in
Source: https://developers.tassyir.io/api-reference/developer/cli-sign-in/approve-a-cli-sign-in

/openapi/openapi.developer.json post /developer/cli/device/approve
The approval page's route (dashboard JWT ONLY: a developer token can never approve a sign-in). The code travels in the body; dashes, spaces and case are ignored. An unknown, expired or someone else's code is one answer, 404 `CLI_CODE_NOT_FOUND`. 10 approvals per user an hour; 10 wrong codes per user and 30 per IP an hour. Only on the developer's click, never automatically. Idempotent. The CLI's next poll receives the token, and the developer is told (a bell notification and a push).

Takes the dashboard session ONLY: a developer token is refused here, so a stolen CLI token can never approve a new sign-in.



# Deny a CLI sign-in
Source: https://developers.tassyir.io/api-reference/developer/cli-sign-in/deny-a-cli-sign-in

/openapi/openapi.developer.json post /developer/cli/device/deny
The approval page's route (dashboard JWT ONLY: a developer token can never approve a sign-in). The code travels in the body; dashes, spaces and case are ignored. An unknown, expired or someone else's code is one answer, 404 `CLI_CODE_NOT_FOUND`. 10 approvals per user an hour; 10 wrong codes per user and 30 per IP an hour. Works until the token is issued; a suspended account may still deny.

Takes the dashboard session ONLY: a developer token is refused here, so a stolen CLI token can never approve a new sign-in.



# Look a sign-in up by its user code
Source: https://developers.tassyir.io/api-reference/developer/cli-sign-in/look-a-sign-in-up-by-its-user-code

/openapi/openapi.developer.json post /developer/cli/device/lookup
The approval page's route (dashboard JWT ONLY: a developer token can never approve a sign-in). The code travels in the body; dashes, spaces and case are ignored. An unknown, expired or someone else's code is one answer, 404 `CLI_CODE_NOT_FOUND`. 10 approvals per user an hour; 10 wrong codes per user and 30 per IP an hour. Show what is asking (client, device name, when, the country it started from) before the developer decides.

Takes the dashboard session ONLY: a developer token is refused here, so a stolen CLI token can never approve a new sign-in.



# Poll for the developer token (RFC 8628 §3.4)
Source: https://developers.tassyir.io/api-reference/developer/cli-sign-in/poll-for-the-developer-token-rfc-8628-§34

/openapi/openapi.developer.json post /developer/cli/token
Every `interval` seconds: `authorization_pending` until the developer decides; `slow_down` (HTTP 400) when a poll comes too soon, after which the interval is 5 seconds longer (at most 60); stop on `access_denied`, `expired_token` or `invalid_grant`. A device code yields one token, once. 30 unknown device codes per IP a minute (429 `slow_down`).

Public: the CLI holds nothing yet.



# Start a CLI sign-in (RFC 8628 §3.1)
Source: https://developers.tassyir.io/api-reference/developer/cli-sign-in/start-a-cli-sign-in-rfc-8628-§31

/openapi/openapi.developer.json post /developer/cli/device-code
Print `user_code`, open `verification_uri_complete` (it only pre-fills the code: the developer approves on the page, signed in to the dashboard), then poll `POST /developer/cli/token` every `interval` seconds. 10 sign-ins per IP every 10 minutes. Errors are OAuth's `{ error, error_description }`.

Public: the CLI holds nothing yet.



# List your live developer tokens
Source: https://developers.tassyir.io/api-reference/developer/cli-tokens/list-your-live-developer-tokens

/openapi/openapi.developer.json get /developer/cli/tokens
Newest first, at most 100; `current` marks the one this request was made with.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Revoke one of your developer tokens
Source: https://developers.tassyir.io/api-reference/developer/cli-tokens/revoke-one-of-your-developer-tokens

/openapi/openapi.developer.json delete /developer/cli/tokens/{tokenId}
Revoking a revoked token answers the same.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Revoke the token this request is made with (`tassyir logout`)
Source: https://developers.tassyir.io/api-reference/developer/cli-tokens/revoke-the-token-this-request-is-made-with-`tassyir-logout`

/openapi/openapi.developer.json delete /developer/cli/tokens/current
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Sign out of every CLI
Source: https://developers.tassyir.io/api-reference/developer/cli-tokens/sign-out-of-every-cli

/openapi/openapi.developer.json delete /developer/cli/tokens
Revokes every token of yours, at once (tokens are never cached).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Create a dev store
Source: https://developers.tassyir.io/api-reference/developer/dev-stores/create-a-dev-store

/openapi/openapi.developer.json post /developer/dev-stores
A business you own, with one store on a `dev-xxxxxxxx` subdomain and, unless `seed: false`, synthetic data (30 products, 64 buyers on fake phones, 200 orders in every state over 58 wilayas). It reaches no outside party and costs nothing. At most 3 per developer, 3 creates a minute.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List your dev stores
Source: https://developers.tassyir.io/api-reference/developer/dev-stores/list-your-dev-stores

/openapi/openapi.developer.json get /developer/dev-stores
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List an app's installations, with their webhooks' health
Source: https://developers.tassyir.io/api-reference/developer/installations/list-an-apps-installations-with-their-webhooks-health

/openapi/openapi.developer.json get /developer/apps/{appId}/installations
Newest first. `limit` 1-100 (default 50).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Delete a listing image
Source: https://developers.tassyir.io/api-reference/developer/listing/delete-a-listing-image

/openapi/openapi.developer.json delete /developer/apps/{appId}/listing/media/{mediaId}
Refused while your draft names it (remove it from the draft first) or the live listing shows it.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Get your app's listing
Source: https://developers.tassyir.io/api-reference/developer/listing/get-your-apps-listing

/openapi/openapi.developer.json get /developer/apps/{appId}/listing
The draft you edit (an app without one reads its names only), what it still needs before you can submit it (`issues`), the live listing the marketplace shows (null until Tassyir approves one) and every listing image.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Replace your app's draft listing
Source: https://developers.tassyir.io/api-reference/developer/listing/replace-your-apps-draft-listing

/openapi/openapi.developer.json put /developer/apps/{appId}/listing
The whole draft: a field you leave out (or send `null`) is cleared. Every rule is checked at once (`LISTING_INVALID` lists each problem with its `path`); an incomplete draft is saved and its gaps come back as `issues`. Plain text only: no HTML, no Markdown links, no invisible characters. The draft never reaches the marketplace by itself: Tassyir reviews it first.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Upload a listing image
Source: https://developers.tassyir.io/api-reference/developer/listing/upload-a-listing-image

/openapi/openapi.developer.json post /developer/apps/{appId}/listing/media
One image a call, as `multipart/form-data`: the file in `file`, its `kind`. The BYTES decide what it is: PNG, JPEG or WebP (never SVG or GIF), at most 2 MB. An icon is square, 512 to 1200 px; a desktop screenshot 16:9 from 1600x900 to 3200x1800; a mobile one 9:16 from 900x1600 to 1800x3200. An app holds at most 20 images (drafts included), and a developer uploads at most 30 every 10 minutes. An image no draft names is deleted 7 days after it was uploaded.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Delete your reply to a rating
Source: https://developers.tassyir.io/api-reference/developer/ratings/delete-your-reply-to-a-rating

/openapi/openapi.developer.json delete /developer/apps/{appId}/ratings/{ratingId}/reply
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List your app's ratings
Source: https://developers.tassyir.io/api-reference/developer/ratings/list-your-apps-ratings

/openapi/openapi.developer.json get /developer/apps/{appId}/ratings
The published ratings, newest first, with the average and count the marketplace shows. `limit` 1-50 (default 20). A rating Tassyir hid is not listed.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Reply to a rating
Source: https://developers.tassyir.io/api-reference/developer/ratings/reply-to-a-rating

/openapi/openapi.developer.json put /developer/apps/{appId}/ratings/{ratingId}/reply
One reply per rating, shown under it; sending again replaces it. Plain text, 1-1,000 characters, without links, email addresses, phone numbers or insults. The merchant is told of your first reply.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Report a rating to Tassyir
Source: https://developers.tassyir.io/api-reference/developer/ratings/report-a-rating-to-tassyir

/openapi/openapi.developer.json post /developer/apps/{appId}/ratings/{ratingId}/report
A rating that is off topic, shares personal data, comes from a competitor, is abusive or is spam. Tassyir decides; reporting again while your report is open changes nothing.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Add a note for the reviewer
Source: https://developers.tassyir.io/api-reference/developer/review/add-a-note-for-the-reviewer

/openapi/openapi.developer.json post /developer/apps/{appId}/submissions/{reviewId}/notes
Plain text: test steps, a demo account on your service, why the version needs a scope. While the case is open; at most 20 notes.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Get a review case
Source: https://developers.tassyir.io/api-reference/developer/review/get-a-review-case

/openapi/openapi.developer.json get /developer/apps/{appId}/submissions/{reviewId}
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List your app's review cases
Source: https://developers.tassyir.io/api-reference/developer/review/list-your-apps-review-cases

/openapi/openapi.developer.json get /developer/apps/{appId}/submissions
Newest first: your submissions and the `version` cases a new version opened. `limit` 1-100 (default 20).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Put your app back in the marketplace
Source: https://developers.tassyir.io/api-reference/developer/review/put-your-app-back-in-the-marketplace

/openapi/openapi.developer.json post /developer/apps/{appId}/relist
Only after you delisted it: an app Tassyir delisted is relisted by Tassyir (`APP_NOT_LISTABLE` `delisted_by_tassyir`).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Read a dry run of the review checks
Source: https://developers.tassyir.io/api-reference/developer/review/read-a-dry-run-of-the-review-checks

/openapi/openapi.developer.json get /developer/apps/{appId}/review-checks/{runId}
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Run the review checks as a dry run
Source: https://developers.tassyir.io/api-reference/developer/review/run-the-review-checks-as-a-dry-run

/openapi/openapi.developer.json post /developer/apps/{appId}/review-checks
What a submission would find now, on your draft listing and latest version, without submitting: every check of the checklist (it fetches your privacy policy and admin page and sends test deliveries, signed and forged, to your webhook endpoints). Queued: read the result with the run id (kept 24 hours). At most 5 per app per hour.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Submit the app for the marketplace
Source: https://developers.tassyir.io/api-reference/developer/review/submit-the-app-for-the-marketplace

/openapi/openapi.developer.json post /developer/apps/{appId}/submissions
Snapshots your DRAFT listing and names your LATEST version, for `public` (browsed and searched) or `unlisted` (installs from its link) distribution: a `listing` review case, `checking` first (the automated checklist), then `submitted` or `checks_failed`. A new submission replaces an open case. Needs the current developer terms accepted. Tassyir aims at 5 working days for a first review, 2 for a resubmission.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Take your app out of the marketplace
Source: https://developers.tassyir.io/api-reference/developer/review/take-your-app-out-of-the-marketplace

/openapi/openapi.developer.json post /developer/apps/{appId}/delist
Out of the catalogue and search, no new installs; existing installations keep working. Undo with relist.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Withdraw a review case
Source: https://developers.tassyir.io/api-reference/developer/review/withdraw-a-review-case

/openapi/openapi.developer.json post /developer/apps/{appId}/submissions/{reviewId}/withdraw
An open case only. A version that waited for it is retired (never released); upload a new one when ready.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List an app's client secrets
Source: https://developers.tassyir.io/api-reference/developer/secrets/list-an-apps-client-secrets

/openapi/openapi.developer.json get /developer/apps/{appId}/credentials
Newest first, at most 50. Never a secret, never its hash.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Mint a client secret (the first, or a rotation)
Source: https://developers.tassyir.io/api-reference/developer/secrets/mint-a-client-secret-the-first-or-a-rotation

/openapi/openapi.developer.json post /developer/apps/{appId}/credentials
The secret is in this answer ONCE. Minting while other secrets are live is the rotation: each live secret with no end date gets `expiresAt = now + 24 h`. At most 3 live secrets per app; 10 minted per developer per hour. No body.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Revoke a client secret now
Source: https://developers.tassyir.io/api-reference/developer/secrets/revoke-a-client-secret-now

/openapi/openapi.developer.json delete /developer/apps/{appId}/credentials/{credentialId}
The token endpoint refuses it from this moment; access tokens already issued live out their hour. Idempotent. Allowed on a suspended account and a read-only app: a leaked secret must always be killable.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Get one version, with its manifest
Source: https://developers.tassyir.io/api-reference/developer/versions/get-one-version-with-its-manifest

/openapi/openapi.developer.json get /developer/apps/{appId}/versions/{version}
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# List an app's versions
Source: https://developers.tassyir.io/api-reference/developer/versions/list-an-apps-versions

/openapi/openapi.developer.json get /developer/apps/{appId}/versions
Newest first, without their manifests. `limit` 1-100 (default 20); `cursor` is the previous `nextCursor` (versions below that number).

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Upload a version of the app's manifest
Source: https://developers.tassyir.io/api-reference/developer/versions/upload-a-version-of-the-apps-manifest

/openapi/openapi.developer.json post /developer/apps/{appId}/versions
The body is at most 328 KB (8 MB + 128 KB while Tassyir Hosting is on) and nests at most 16 levels (its own parser); a larger body is 413 `PAYLOAD_TOO_LARGE` with `limitBytes`, `hostingAvailable` and a `fix` saying why (while hosting is off, only a version carrying a bundle is that large). The validator checks the manifest (every error at once); `handle` must be the app's; a manifest identical to the latest version's (and, hosted, the same bundle) is refused. An external version is numbered latest + 1, approved and current at once, except for a LISTED app: there it must subscribe the three compliance topics and name a supported API version (400 `REVIEW_CHECKS_FAILED`, nothing stored), and a version that adds scopes, data hosts or storefront code waits `in_review` for a person (a `version` review case opens by itself). A hosted version (`hosting.mode = "tassyir"`, while Tassyir Hosting is on and open to your developer account) carries its `bundle`, stored before the version is created `scanning`; it is scanned, uploaded and released by the hosting pipeline. Storefront blocks (`[[storefront.blocks]]`, scope `write_storefront`): each block's template and stylesheet are read from the version's files (an external version's `assets`, a hosted version's `bundle.files`) and checked by `@tassyir/storefront-blocks`' `validateBlock`, the same function the CLI runs; the first block that fails is 400 `BLOCK_TEMPLATE_INVALID` with the package's errors (each with `line`, `column` and `fix`), a missing, unused or oversized file 400 `BLOCK_ASSETS_INVALID`, and nothing is stored. 30 uploads per developer per hour, 10 hosted a day.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# One delivery of the log
Source: https://developers.tassyir.io/api-reference/developer/webhooks/one-delivery-of-the-log

/openapi/openapi.developer.json get /developer/apps/{appId}/webhooks/deliveries/{deliveryId}
Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Re-enable an installation's webhooks
Source: https://developers.tassyir.io/api-reference/developer/webhooks/re-enable-an-installations-webhooks

/openapi/openapi.developer.json post /developer/apps/{appId}/installations/{installationId}/webhooks/enable
After a 410 or 3 days of continuous failure disabled them: clears the disable and the failure clock. Deliveries recorded `skipped` meanwhile stay skipped (replay the ones you need). Idempotent. No body.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Send a delivery again, now
Source: https://developers.tassyir.io/api-reference/developer/webhooks/send-a-delivery-again-now

/openapi/openapi.developer.json post /developer/apps/{appId}/webhooks/deliveries/{deliveryId}/replay
One more attempt through the real sender, inline, with the same `webhook-id` (a receiver that deduplicates on it ignores a replay of something it processed). The attempt is final: no retry schedule after a replay. Refused while the delivery is still pending. 60 replays per app and 120 per developer every 10 minutes. No body.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Send a test delivery to an installation
Source: https://developers.tassyir.io/api-reference/developer/webhooks/send-a-test-delivery-to-an-installation

/openapi/openapi.developer.json post /developer/apps/{appId}/installations/{installationId}/webhooks/test
A synthetic, signed delivery of a sample body (`tassyir-test: true`, `webhook-id: dlv_test_…`, envelope id `evt_0`); nothing is recorded and a 410 disables nothing. Needs an active installation whose version subscribes to the topic and was granted its scope. 20 tests per app and 40 per developer every 10 minutes.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# The app's delivery log
Source: https://developers.tassyir.io/api-reference/developer/webhooks/the-apps-delivery-log

/openapi/openapi.developer.json get /developer/apps/{appId}/webhooks/deliveries
Newest first, the last 30 days, metadata only (never a body or a URL). `limit` 1-100 (default 50); `since` is inclusive, `until` exclusive.

Takes the dashboard session or a developer token (`tsy_dt_…`); either way the caller is the signed-in user, and only their own account, apps and tokens are reachable.



# Claude Code plugin
Source: https://developers.tassyir.io/claude-code

Give Claude Code the Tassyir app contract and the developer MCP server with one plugin.

The `tassyir` plugin gives Claude Code what it needs to build a Tassyir app:

* the **developer MCP server**, [`@tassyir/dev-mcp`](/packages/dev-mcp): it searches and reads these guides, looks up any Admin API operation and webhook body, validates `tassyir.app.toml` with the API's own validator, starts a new app from the starter, and sends test webhooks and creates dev stores with your `tassyir login`;
* the **`tassyir-app` skill**: the app contract (manifest, scopes, tokens, webhooks, Admin API, App Bridge, dev stores), the same file [`create-tassyir-app`](/packages/create-tassyir-app) writes into every new project.

## Install

In Claude Code, add Tassyir's plugin marketplace, then install the plugin:

```text theme={null}
/plugin marketplace add tassyir/apps-sdk
/plugin install tassyir@tassyir
```

From a terminal, the same is:

```bash theme={null}
claude plugin marketplace add tassyir/apps-sdk
claude plugin install tassyir@tassyir
```

The marketplace is the [`tassyir/apps-sdk`](https://github.com/tassyir/apps-sdk) repository. The plugin runs the `@tassyir/dev-mcp` release it names, with `npx`, so you need Node 22.18 or later.

## Update

For a newer release later:

```bash theme={null}
claude plugin marketplace update tassyir
claude plugin update tassyir@tassyir
```

## Without the plugin

The server alone works in any MCP client. In Claude Code:

```bash theme={null}
claude mcp add tassyir -- npx -y @tassyir/dev-mcp
```

The tools that act on your Tassyir account use the sign-in of the [`tassyir` CLI](/packages/cli). Sign in once, in a terminal:

```bash theme={null}
npx tassyir login
```

Every tool, its input and its answers: [`@tassyir/dev-mcp`](/packages/dev-mcp).


# API_BUSY
Source: https://developers.tassyir.io/errors/api-busy

HTTP 503, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/api-busy`; its `title`: API busy.

## What to do

HTTP 503. The API was too busy to take your call and did **nothing**. Wait
`Retry-After` (1 second) and send the same call again, a write included.

The answer's `fix`: Nothing was done: wait the number of seconds in Retry-After, then retry with exponential backoff.

## Answered by

Every operation of the Admin API, with HTTP 503.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_DATA_KEY_NOT_DECLARED
Source: https://developers.tassyir.io/errors/app-data-key-not-declared

HTTP 400, from PUT /data/{ownerType}/{ownerId}/{key}.

Its problem `type`: `https://developers.tassyir.io/errors/app-data-key-not-declared`; its `title`: App data key not declared.

## What to do

HTTP 400. Your installation's version does not declare that key for that owner
type. Declare it under `[[data.definitions]]`, upload, and have the merchant
accept the update.

The answer's `fix`: Declare the key for this owner under \[\[data.definitions]] in the app's manifest; it can be written once the merchant accepts that version.

## Answered by

HTTP 400, from:

* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_DATA_LIMIT_REACHED
Source: https://developers.tassyir.io/errors/app-data-limit-reached

HTTP 409, from PUT /data/{ownerType}/{ownerId}/{key}.

Its problem `type`: `https://developers.tassyir.io/errors/app-data-limit-reached`; its `title`: App data limit reached.

## What to do

Delete values the app no longer needs with DELETE /data/\{ownerType}/\{ownerId}/\{key}, then retry; rewriting a key that exists is never refused.

## Answered by

HTTP 409, from:

* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_DATA_VALUE_INVALID
Source: https://developers.tassyir.io/errors/app-data-value-invalid

HTTP 400, from PUT /data/{ownerType}/{ownerId}/{key}.

Its problem `type`: `https://developers.tassyir.io/errors/app-data-value-invalid`; its `title`: App data value invalid.

## What to do

Send a value of the declaredType the manifest gives this key, without the part named in reason.

## Answered by

HTTP 400, from:

* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_DATA_VALUE_TOO_LARGE
Source: https://developers.tassyir.io/errors/app-data-value-too-large

HTTP 400, from PUT /data/{ownerType}/{ownerId}/{key}.

Its problem `type`: `https://developers.tassyir.io/errors/app-data-value-too-large`; its `title`: App data value too large.

## What to do

Keep each value within limitBytes of compact JSON: split it across several keys, or store a reference instead.

## Answered by

HTTP 400, from:

* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_TOKEN_INVALID
Source: https://developers.tassyir.io/errors/app-token-invalid

HTTP 401, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/app-token-invalid`; its `title`: Access token invalid.

## What to do

HTTP 401. The token is unknown, expired or revoked, or its installation or app is
no longer active. Refresh it once (the SDK does). If the refresh is refused,
the installation was uninstalled, suspended or had its scopes changed: an
embedded app gets a new token on the next page view, a headless app needs a
new install code.

The answer's `fix`: Get a new access token from POST /apps/oauth/token, then retry the request.

## Answered by

Every operation of the Admin API, with HTTP 401.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# APP_TOKEN_REQUIRED
Source: https://developers.tassyir.io/errors/app-token-required

HTTP 401, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/app-token-required`; its `title`: Access token required.

## What to do

HTTP 401. No `Authorization: Bearer` header. Send the installation's access token.

The answer's `fix`: Send the access token in the Authorization header as Bearer tsy\_at\_….

## Answered by

Every operation of the Admin API, with HTTP 401.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BAD_REQUEST
Source: https://developers.tassyir.io/errors/bad-request

HTTP 400, from 23 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/bad-request`; its `title`: Bad request.

## What to do

Correct the request as the detail says, then retry.

## Answered by

HTTP 400, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a refusal with HTTP 400 that carries no more specific code.

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BRAND_NOT_FOUND
Source: https://developers.tassyir.io/errors/brand-not-found

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/brand-not-found`; its `title`: Bad request.

## What to do

Send the id of a brand of the product's store, or null for none; the ids in brandIds are not.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BULK_EXPORT_IN_PROGRESS
Source: https://developers.tassyir.io/errors/bulk-export-in-progress

HTTP 409, from POST /bulk/exports.

Its problem `type`: `https://developers.tassyir.io/errors/bulk-export-in-progress`; its `title`: Conflict.

## What to do

Wait for the export named in bulkExportId to finish (the bulk/finished webhook, or GET /bulk/exports/\{id}), then ask again.

## Answered by

HTTP 409, from:

* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BULK_EXPORT_RATE_LIMITED
Source: https://developers.tassyir.io/errors/bulk-export-rate-limited

HTTP 429, from POST /bulk/exports.

Its problem `type`: `https://developers.tassyir.io/errors/bulk-export-rate-limited`; its `title`: Too many requests.

## What to do

Wait the number of seconds in Retry-After; keep a finished export and read it again instead of exporting the same list twice.

## Answered by

HTTP 429, from:

* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BULK_EXPORTS_NOT_CONFIGURED
Source: https://developers.tassyir.io/errors/bulk-exports-not-configured

HTTP 503, from POST /bulk/exports.

Its problem `type`: `https://developers.tassyir.io/errors/bulk-exports-not-configured`; its `title`: Service unavailable.

## What to do

Page through the list route instead, or retry later.

## Answered by

HTTP 503, from:

* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# BUSINESS_RATE_LIMITED
Source: https://developers.tassyir.io/errors/business-rate-limited

HTTP 429, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/business-rate-limited`; its `title`: Business's rate limit exceeded.

## What to do

HTTP 429. All the apps of this business together are past its ceiling. Wait
`Retry-After` seconds; other apps are using the room, so slow down.

The answer's `fix`: Wait the number of seconds in Retry-After, then retry; every app of this business shares this budget, so spread requests over time.

## Answered by

Every operation of the Admin API, with HTTP 429.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# CANCEL_NOTE_REQUIRED
Source: https://developers.tassyir.io/errors/cancel-note-required

HTTP 400, from POST /orders/{id}/cancel.

Its problem `type`: `https://developers.tassyir.io/errors/cancel-note-required`; its `title`: Bad request.

## What to do

Send a note with this cancel reason: the merchant set it to require one.

## Answered by

HTTP 400, from:

* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# CANCEL_REASON_INVALID
Source: https://developers.tassyir.io/errors/cancel-reason-invalid

HTTP 400, from POST /orders/{id}/cancel.

Its problem `type`: `https://developers.tassyir.io/errors/cancel-reason-invalid`; its `title`: Bad request.

## What to do

Read GET /cancel-reasons again and send the id of one of its reasons, or no reason.

## Answered by

HTTP 400, from:

* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_CONDITIONAL_LIMIT
Source: https://developers.tassyir.io/errors/collection-conditional-limit

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/collection-conditional-limit`; its `title`: Conflict.

## What to do

Make this collection without conditions, or remove the conditions of another first: the store has its maximum of collections with conditions (limit).

## Answered by

HTTP 409, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_DEPTH_LIMIT
Source: https://developers.tassyir.io/errors/collection-depth-limit

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/collection-depth-limit`; its `title`: Conflict.

## What to do

Choose a parent higher in the tree: collections nest at most limit levels deep, with their subcollections.

## Answered by

HTTP 409, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_NOT_FOUND
Source: https://developers.tassyir.io/errors/collection-not-found

HTTP 400, from POST /products.

Its problem `type`: `https://developers.tassyir.io/errors/collection-not-found`; its `title`: Bad request.

## What to do

Name only collections of the product's store that still exist; the ids in categoryIds are not.

## Answered by

HTTP 400, from:

* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_PARENT_CYCLE
Source: https://developers.tassyir.io/errors/collection-parent-cycle

HTTP 409, from PATCH /collections/{id}.

Its problem `type`: `https://developers.tassyir.io/errors/collection-parent-cycle`; its `title`: Conflict.

## What to do

Choose a parent that is neither this collection nor one of its own subcollections.

## Answered by

HTTP 409, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_PARENT_NOT_FOUND
Source: https://developers.tassyir.io/errors/collection-parent-not-found

HTTP 404, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/collection-parent-not-found`; its `title`: Not found.

## What to do

Send as parentId a collection of the same store that still exists, or null for a top-level collection.

## Answered by

HTTP 404, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_PRODUCT_WRONG_STORE
Source: https://developers.tassyir.io/errors/collection-product-wrong-store

HTTP 400, from PATCH /collections/{id}/products.

Its problem `type`: `https://developers.tassyir.io/errors/collection-product-wrong-store`; its `title`: Bad request.

## What to do

Add only products of the collection's store; the ids in productIds are not.

## Answered by

HTTP 400, from:

* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# COLLECTION_RULE_INVALID
Source: https://developers.tassyir.io/errors/collection-rule-invalid

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/collection-rule-invalid`; its `title`: Bad request.

## What to do

Correct the condition at index as reason says; a brand or tag it names must be the store's own.

## Answered by

HTTP 400, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# CONFLICT
Source: https://developers.tassyir.io/errors/conflict

A refusal with HTTP 409 that carries no more specific code.

Its problem `type`: `https://developers.tassyir.io/errors/conflict`; its `title`: Conflict.

## What to do

Read the resource again and act on its current state; do not retry the same request unchanged.

## Answered by

The code of a refusal with HTTP 409 that carries no more specific code. Any operation may answer it.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# DELIVERY_SPEED_UNAVAILABLE
Source: https://developers.tassyir.io/errors/delivery-speed-unavailable

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/delivery-speed-unavailable`; its `title`: Bad request.

## What to do

Use the standard speed: economy is not priced for this commune and delivery method.

## Answered by

HTTP 400, from:

* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# DELIVERY_SPEED_UNSUPPORTED
Source: https://developers.tassyir.io/errors/delivery-speed-unsupported

HTTP 400, from PATCH /orders/{id}.

Its problem `type`: `https://developers.tassyir.io/errors/delivery-speed-unsupported`; its `title`: Bad request.

## What to do

Use the standard speed: the order's carrier has no economy service.

## Answered by

HTTP 400, from:

* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# DEV_STORE_ORDER_LIMIT_REACHED
Source: https://developers.tassyir.io/errors/dev-store-order-limit-reached

HTTP 429, from POST /orders.

Its problem `type`: `https://developers.tassyir.io/errors/dev-store-order-limit-reached`; its `title`: Too many requests.

## What to do

Wait the number of seconds in retryAfterSeconds (until the next day in Algiers): a dev store takes at most limit new orders a day.

## Answered by

HTTP 429, from:

* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# FORBIDDEN
Source: https://developers.tassyir.io/errors/forbidden

HTTP 403, from 4 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/forbidden`; its `title`: Forbidden.

## What to do

Do not retry the same request: the detail says what this installation may not do.

## Answered by

HTTP 403, from:

* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)

Also the code of a refusal with HTTP 403 that carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# HOSTED_CALL_REFUSED
Source: https://developers.tassyir.io/errors/hosted-call-refused

HTTP 401, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/hosted-call-refused`; its `title`: Hosted call refused.

## What to do

HTTP 401. A hosted app's call through `ctx.props.TASSYIR` was refused: its
installation is uninstalled or suspended, or no longer runs a released
version. It is also the answer during an `app/uninstalled` or
`business/redact` delivery. Make the call from the request that received
`ctx.props.TASSYIR`; if the installation is active, retry after a short wait
([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The answer's `fix`: Call the Admin API through ctx.props.TASSYIR.fetch from the request that received it; if the installation is still active, retry after a short wait.

## Answered by

Every operation of the Admin API, with HTTP 401.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# HOSTED_PATH_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/hosted-path-not-allowed

HTTP 400, from a hosted app's TASSYIR binding, before the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/hosted-path-not-allowed`; its `title`: Not an Admin API path.

## What to do

HTTP 400. The call was not to an Admin API path. Call `/apps/<version>/…`
with segments of letters, digits, `_` and `-` only: no other path, no `//`,
no trailing `/`, no percent-encoding and no `;`. The binding also reads
Tassyir's two public key documents, with `GET` at exactly
`/apps/webhook-keys` and `/apps/.well-known/jwks.json` (another method there
is `METHOD_NOT_ALLOWED`).

## Answered by

A hosted app's `ctx.props.TASSYIR` binding answers it itself, before the call reaches the Admin API, so the problem has no `requestId` and the API's reference does not list it. How the binding calls the API: [Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# HTML_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/html-not-allowed

HTTP 400, from 4 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/html-not-allowed`; its `title`: Markup not allowed.

## What to do

Send plain formatted HTML (paragraphs, headings, lists, links, Tassyir CDN images) without the parts listed in problems.

## Answered by

HTTP 400, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IDEMPOTENCY_KEY_IN_USE
Source: https://developers.tassyir.io/errors/idempotency-key-in-use

HTTP 409, from 28 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/idempotency-key-in-use`; its `title`: Idempotency-Key in use.

## What to do

HTTP 409. A request with the same key is still running. Wait, then retry with the
same key: you will get its answer.

The answer's `fix`: Wait for the first request with this Idempotency-Key to finish, then retry.

## Answered by

HTTP 409, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IDEMPOTENCY_KEY_INVALID
Source: https://developers.tassyir.io/errors/idempotency-key-invalid

HTTP 400, from 28 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/idempotency-key-invalid`; its `title`: Invalid Idempotency-Key.

## What to do

Send 1 to 255 visible ASCII characters, for example a UUID.

## Answered by

HTTP 400, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IDEMPOTENCY_KEY_REUSED
Source: https://developers.tassyir.io/errors/idempotency-key-reused

HTTP 422, from 28 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/idempotency-key-reused`; its `title`: Idempotency-Key reused.

## What to do

HTTP 422. You reused an `Idempotency-Key` with another method, path, query or
body. Use a new key for a different write.

The answer's `fix`: Use a new Idempotency-Key for a different request; reuse a key only to retry the identical request.

## Answered by

HTTP 422, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IDEMPOTENCY_UNAVAILABLE
Source: https://developers.tassyir.io/errors/idempotency-unavailable

HTTP 503, from 28 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/idempotency-unavailable`; its `title`: Idempotency store unavailable.

## What to do

HTTP 503. Tassyir cannot check idempotency keys right now, so the write was not
attempted. Retry after `Retry-After` with the same key.

The answer's `fix`: Retry the same request with the same Idempotency-Key in a few seconds.

## Answered by

HTTP 503, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IMAGE_FETCH_FAILED
Source: https://developers.tassyir.io/errors/image-fetch-failed

HTTP 400, from POST /images.

Its problem `type`: `https://developers.tassyir.io/errors/image-fetch-failed`; its `title`: Image could not be downloaded.

## What to do

Check that the address opens the image from the public internet over https with a valid certificate; retry later if the server was down.

## Answered by

HTTP 400, from:

* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IMAGE_QUOTA_REACHED
Source: https://developers.tassyir.io/errors/image-quota-reached

HTTP 429, from POST /images.

Its problem `type`: `https://developers.tassyir.io/errors/image-quota-reached`; its `title`: Image upload quota reached.

## What to do

Wait the number of seconds in Retry-After, then upload the rest more slowly.

## Answered by

HTTP 429, from:

* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IMAGE_TOO_LARGE
Source: https://developers.tassyir.io/errors/image-too-large

HTTP 400, from POST /images.

Its problem `type`: `https://developers.tassyir.io/errors/image-too-large`; its `title`: Image too large.

## What to do

Send a smaller image: at most 10 MB, 12,000 pixels on a side and 100 megapixels.

## Answered by

HTTP 400, from:

* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IMAGE_TYPE_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/image-type-not-allowed

HTTP 400, from POST /images.

Its problem `type`: `https://developers.tassyir.io/errors/image-type-not-allowed`; its `title`: Not a supported image.

## What to do

Send a JPEG, PNG, GIF or WebP image; convert an SVG or any other format to one of these first.

## Answered by

HTTP 400, from:

* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# IMAGE_URL_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/image-url-not-allowed

HTTP 400, from POST /images.

Its problem `type`: `https://developers.tassyir.io/errors/image-url-not-allowed`; its `title`: Image address not allowed.

## What to do

Send the https address (port 443, no user or password) of the image on a public web server, by its host name.

## Answered by

HTTP 400, from:

* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# INSUFFICIENT_AT_LOCATION
Source: https://developers.tassyir.io/errors/insufficient-at-location

HTTP 409, from POST /inventory-levels/{id}/adjust.

Its problem `type`: `https://developers.tassyir.io/errors/insufficient-at-location`; its `title`: Conflict.

## What to do

Read the level again and remove at most what it holds: stock never goes below zero.

## Answered by

HTTP 409, from:

* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# INTERNAL_ERROR
Source: https://developers.tassyir.io/errors/internal-error

HTTP 500, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/internal-error`; its `title`: Internal error.

## What to do

HTTP 500. Tassyir's fault. Retry reads with backoff; retry writes only with the
same `Idempotency-Key`. Quote the `requestId` if it persists.

The answer's `fix`: Retry with exponential backoff; if it keeps failing, report the requestId to Tassyir.

## Answered by

Every operation of the Admin API, with HTTP 500.

Also the code of a 5xx failure with a status other than 503, when it carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# INVALID_CURSOR
Source: https://developers.tassyir.io/errors/invalid-cursor

HTTP 400, from 13 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/invalid-cursor`; its `title`: Invalid cursor.

## What to do

HTTP 400. The `cursor` is not this list's, was edited, or was made with other
filters. Send `nextCursor` back unchanged, with the same filters; to change a
filter, start again without a cursor.

The answer's `fix`: Pass the nextCursor of the previous page unchanged with the same filters, or start again without a cursor.

## Answered by

HTTP 400, from:

* [`GET /bulk/exports`](/api-reference/admin/bulk-exports/list-the-installations-exports)
* [`GET /collections`](/api-reference/admin/collections/list-collections)
* [`GET /customers`](/api-reference/admin/customers/list-customers)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /delivery-agents`](/api-reference/admin/delivery/list-delivery-agents)
* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /offers`](/api-reference/admin/offers/list-offers)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`GET /orders`](/api-reference/admin/orders/list-orders)
* [`GET /orders/{id}/comments`](/api-reference/admin/orders/list-an-orders-comments)
* [`GET /products`](/api-reference/admin/products/list-products)
* [`GET /stores`](/api-reference/admin/stores/list-stores)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# INVALID_FIELDS
Source: https://developers.tassyir.io/errors/invalid-fields

HTTP 400, from 49 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/invalid-fields`; its `title`: Unknown fields.

## What to do

HTTP 400. `fields` names a field the resource does not have. `allowedFields`
lists the valid names; fields are top-level only.

The answer's `fix`: Name only fields listed in allowedFields, separated by commas.

## Answered by

HTTP 400, from:

* [`GET /bulk/exports`](/api-reference/admin/bulk-exports/list-the-installations-exports)
* [`GET /bulk/exports/{id}`](/api-reference/admin/bulk-exports/get-an-export)
* [`GET /business`](/api-reference/admin/business/the-business-the-app-is-installed-on)
* [`GET /cancel-reasons`](/api-reference/admin/orders/the-merchants-cancel-reasons)
* [`GET /collections`](/api-reference/admin/collections/list-collections)
* [`GET /collections/{id}`](/api-reference/admin/collections/get-a-collection)
* [`GET /customers`](/api-reference/admin/customers/list-customers)
* [`GET /customers/{id}`](/api-reference/admin/customers/get-a-customer)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/get-a-value)
* [`GET /delivery-agents`](/api-reference/admin/delivery/list-delivery-agents)
* [`GET /delivery-agents/{id}`](/api-reference/admin/delivery/get-a-delivery-agent)
* [`GET /delivery-fee-groups`](/api-reference/admin/delivery/list-delivery-fee-groups)
* [`GET /delivery-fee-groups/{id}`](/api-reference/admin/delivery/get-a-delivery-fee-group)
* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`GET /offers`](/api-reference/admin/offers/list-offers)
* [`GET /offers/{id}`](/api-reference/admin/offers/get-an-offer)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`GET /orders`](/api-reference/admin/orders/list-orders)
* [`GET /orders/{id}`](/api-reference/admin/orders/get-an-order)
* [`GET /orders/{id}/comments`](/api-reference/admin/orders/list-an-orders-comments)
* [`GET /products`](/api-reference/admin/products/list-products)
* [`GET /products/{id}`](/api-reference/admin/products/get-a-product)
* [`GET /stores`](/api-reference/admin/stores/list-stores)
* [`GET /stores/{id}`](/api-reference/admin/stores/get-a-store)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# LOCATION_NOT_FOUND
Source: https://developers.tassyir.io/errors/location-not-found

HTTP 400, 404, from POST /inventory-levels/{id}/adjust.

Its problem `type`: `https://developers.tassyir.io/errors/location-not-found`; its `title`: Bad request.

## What to do

Name an active location of this business, or leave locationId out to use the default location.

## Answered by

HTTP 400, 404, from:

* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# MEDIA_URL_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/media-url-not-allowed

HTTP 400, from 5 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/media-url-not-allowed`; its `title`: Image address not allowed.

## What to do

HTTP 400. An image is not on `https://cdn.tassyir.io/` and not already on the
resource (`field`, `url`). Upload it with `POST /images` first
([Products and collections](/guides/products-and-collections#bring-an-image-onto-the-cdn)).

The answer's `fix`: Upload the image with POST /images and use the URL it answers ([https://cdn.tassyir.io/…](https://cdn.tassyir.io/…)), or keep one this resource already shows; do not link images hosted elsewhere.

## Answered by

HTTP 400, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# METHOD_NOT_ALLOWED
Source: https://developers.tassyir.io/errors/method-not-allowed

A refusal with HTTP 405 that carries no more specific code.

Its problem `type`: `https://developers.tassyir.io/errors/method-not-allowed`; its `title`: Method not allowed.

## What to do

Call the operation with the method its reference names.

## Answered by

The code of a refusal with HTTP 405 that carries no more specific code. Any operation may answer it.

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# NOT_FOUND
Source: https://developers.tassyir.io/errors/not-found

HTTP 404, from 40 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/not-found`; its `title`: Not found.

## What to do

HTTP 404. No such route, or no resource your token can read under that id: a
resource of another store or business, or a malformed id, reads the same.

The answer's `fix`: Check the path and the id; a resource outside this installation's stores reads as not found.

## Answered by

HTTP 404, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`GET /bulk/exports/{id}`](/api-reference/admin/bulk-exports/get-an-export)
* [`GET /business`](/api-reference/admin/business/the-business-the-app-is-installed-on)
* [`GET /collections/{id}`](/api-reference/admin/collections/get-a-collection)
* [`GET /customers/{id}`](/api-reference/admin/customers/get-a-customer)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/get-a-value)
* [`GET /delivery-agents/{id}`](/api-reference/admin/delivery/get-a-delivery-agent)
* [`GET /delivery-fee-groups/{id}`](/api-reference/admin/delivery/get-a-delivery-fee-group)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`GET /offers/{id}`](/api-reference/admin/offers/get-an-offer)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`GET /orders/{id}`](/api-reference/admin/orders/get-an-order)
* [`GET /orders/{id}/comments`](/api-reference/admin/orders/list-an-orders-comments)
* [`GET /products/{id}`](/api-reference/admin/products/get-a-product)
* [`GET /stores/{id}`](/api-reference/admin/stores/get-a-store)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a refusal with HTTP 404 that carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_ARCHIVED
Source: https://developers.tassyir.io/errors/offer-archived

HTTP 409, from 6 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-archived`; its `title`: Conflict.

## What to do

Create a new offer: an archived one is history and cannot be changed.

## Answered by

HTTP 409, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_CODE_INVALID
Source: https://developers.tassyir.io/errors/offer-code-invalid

HTTP 400, from POST /offers/{id}/codes.

Its problem `type`: `https://developers.tassyir.io/errors/offer-code-invalid`; its `title`: Bad request.

## What to do

Send a code of 3 to 30 characters: letters, digits, hyphens and underscores.

## Answered by

HTTP 400, from:

* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_CODE_NOT_FOUND
Source: https://developers.tassyir.io/errors/offer-code-not-found

HTTP 404, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-code-not-found`; its `title`: Not found.

## What to do

Name a code of this offer (GET /offers/\{id}/codes).

## Answered by

HTTP 404, from:

* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_CODE_TAKEN
Source: https://developers.tassyir.io/errors/offer-code-taken

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-code-taken`; its `title`: Conflict.

## What to do

Choose another code: codes are unique across the whole business, disabled ones included.

## Answered by

HTTP 409, from:

* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_ENDED
Source: https://developers.tassyir.io/errors/offer-ended

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-ended`; its `title`: Conflict.

## What to do

Move endsAt to a later date with PATCH /offers/\{id}: an ended offer is not resumed.

## Answered by

HTTP 409, from:

* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_GONE
Source: https://developers.tassyir.io/errors/offer-gone

HTTP 409, from POST /orders.

Its problem `type`: `https://developers.tassyir.io/errors/offer-gone`; its `title`: Conflict.

## What to do

Send the order again: the offer behind the code was deleted, and the retry will list the code in rejectedCodes and create the order without it.

## Answered by

HTTP 409, from:

* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_INVALID
Source: https://developers.tassyir.io/errors/offer-invalid

HTTP 400, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-invalid`; its `title`: Bad request.

## What to do

Correct the fields listed in errors (each has a field and a code), then send the request again.

## Answered by

HTTP 400, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_KIND_IMMUTABLE
Source: https://developers.tassyir.io/errors/offer-kind-immutable

HTTP 400, from PATCH /offers/{id}.

Its problem `type`: `https://developers.tassyir.io/errors/offer-kind-immutable`; its `title`: Bad request.

## What to do

Leave kind and method as the offer has them: create a new offer to change either.

## Answered by

HTTP 400, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_KIND_NOT_AVAILABLE
Source: https://developers.tassyir.io/errors/offer-kind-not-available

HTTP 400, from POST /offers.

Its problem `type`: `https://developers.tassyir.io/errors/offer-kind-not-available`; its `title`: Bad request.

## What to do

Create an offer of a kind the dashboard offers today; the other kinds in the model open later.

## Answered by

HTTP 400, from:

* [`POST /offers`](/api-reference/admin/offers/create-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_LIMIT_REACHED
Source: https://developers.tassyir.io/errors/offer-limit-reached

HTTP 409, from POST /orders.

Its problem `type`: `https://developers.tassyir.io/errors/offer-limit-reached`; its `title`: Conflict.

## What to do

Send the order again: the code (or offer) has no uses left, and the retry will list the code in rejectedCodes as code\_used\_up and create the order without it.

## Answered by

HTTP 409, from:

* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_NOT_CODE_METHOD
Source: https://developers.tassyir.io/errors/offer-not-code-method

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-not-code-method`; its `title`: Conflict.

## What to do

Only an offer created with method "code" has codes; create a code offer to use them.

## Answered by

HTTP 409, from:

* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_NOT_FOUND
Source: https://developers.tassyir.io/errors/offer-not-found

HTTP 404, from 9 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-not-found`; its `title`: Not found.

## What to do

The offer was deleted between the check and the change; read the list again.

## Answered by

HTTP 404, from:

* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_NOT_OWNED
Source: https://developers.tassyir.io/errors/offer-not-owned

HTTP 403, from 11 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-not-owned`; its `title`: Offer not owned by this app.

## What to do

HTTP 403. You tried to change, or read the codes or redemptions of, an offer
your installation did not create: the merchant's own, or another app's. An
app writes only its own offers. Create your own offer with `POST /offers` and
change that one ([Write offers and codes](/guides/write-offers#you-write-only-the-offers-you-own)).
The merchant's dashboard has a counterpart you never get: editing or
duplicating an **app-owned** offer there answers 409 `OFFER_APP_OWNED`,
because such an offer is changed in the app that owns it.

The answer's `fix`: Create your own offer with POST /offers and change that one; the merchant edits their own offers in the dashboard.

## Answered by

HTTP 403, from:

* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_NOT_PUBLISHED
Source: https://developers.tassyir.io/errors/offer-not-published

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-not-published`; its `title`: Conflict.

## What to do

Publish the draft with POST /offers/\{id}/publish first.

## Answered by

HTTP 409, from:

* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_STORE_NOT_FOUND
Source: https://developers.tassyir.io/errors/offer-store-not-found

HTTP 404, from POST /offers.

Its problem `type`: `https://developers.tassyir.io/errors/offer-store-not-found`; its `title`: Not found.

## What to do

Send the id of a store of this business that the installation may access (GET /stores).

## Answered by

HTTP 404, from:

* [`POST /offers`](/api-reference/admin/offers/create-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_TARGET_NOT_FOUND
Source: https://developers.tassyir.io/errors/offer-target-not-found

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-target-not-found`; its `title`: Bad request.

## What to do

Target only products, variants and collections of this business that still exist; the ids in the offer's targets are not.

## Answered by

HTTP 400, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_TARGET_OUTSIDE_STORE
Source: https://developers.tassyir.io/errors/offer-target-outside-store

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-target-outside-store`; its `title`: Bad request.

## What to do

Target only products, variants and collections of the offer's store.

## Answered by

HTTP 400, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# OFFER_VERSION_CONFLICT
Source: https://developers.tassyir.io/errors/offer-version-conflict

HTTP 409, from 4 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/offer-version-conflict`; its `title`: Conflict.

## What to do

Read the offer again (currentVersion is its version now) and send expectedVersion with the change, or leave expectedVersion out.

## Answered by

HTTP 409, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# ORDER_DUPLICATE
Source: https://developers.tassyir.io/errors/order-duplicate

HTTP 409, from POST /orders.

Its problem `type`: `https://developers.tassyir.io/errors/order-duplicate`; its `title`: Duplicate order.

## What to do

Do not retry: the buyer already has this order, which the merchant handles.

## Answered by

HTTP 409, from:

* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# ORDER_LIMIT_REACHED
Source: https://developers.tassyir.io/errors/order-limit-reached

HTTP 403, from POST /orders/{id}/confirm.

Its problem `type`: `https://developers.tassyir.io/errors/order-limit-reached`; its `title`: Order waiting for the plan allowance.

## What to do

HTTP 403. The order is waiting: it is past the plan's order allowance, and
cannot be confirmed until it unlocks (`orders/updated` with `waiting`).

The answer's `fix`: Retry after the merchant upgrades or the plan's next order cycle starts.

## Answered by

HTTP 403, from:

* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# ORDER_NOT_EDITABLE
Source: https://developers.tassyir.io/errors/order-not-editable

HTTP 409, from 4 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/order-not-editable`; its `title`: Order no longer editable.

## What to do

HTTP 409. The order is dispatched, delivered or returned (`orderStatus`): it can
no longer be edited, confirmed or cancelled.

The answer's `fix`: Leave this order as it is: once with a carrier it changes only through the delivery.

## Answered by

HTTP 409, from:

* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# ORDER_PRICING_LOCKED
Source: https://developers.tassyir.io/errors/order-pricing-locked

HTTP 400, from PATCH /orders/{id}.

Its problem `type`: `https://developers.tassyir.io/errors/order-pricing-locked`; its `title`: Bad request.

## What to do

Leave the wilaya, commune and delivery as they are: the order is with a carrier, delivered or returned, so its price no longer changes.

## Answered by

HTTP 400, from:

* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# ORDER_STATUS_CONFLICT
Source: https://developers.tassyir.io/errors/order-status-conflict

HTTP 409, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/order-status-conflict`; its `title`: Status change not allowed.

## What to do

HTTP 409. The order's status does not allow this move (`orderStatus`,
`requestedStatus`): read the order again and decide.

The answer's `fix`: Read the order again and act on its current status; do not retry the same move.

## Answered by

HTTP 409, from:

* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PAYLOAD_TOO_LARGE
Source: https://developers.tassyir.io/errors/payload-too-large

HTTP 413, from 22 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/payload-too-large`; its `title`: Payload too large.

## What to do

Send a smaller body: split the write into several requests.

## Answered by

HTTP 413, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a refusal with HTTP 413 that carries no more specific code.

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PERMISSION_DENIED
Source: https://developers.tassyir.io/errors/permission-denied

HTTP 403, from 54 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/permission-denied`; its `title`: Permission denied.

## What to do

HTTP 403. Your installation lacks the permission the route checks (`permission`).
The `fix` names the scope: add it to the manifest, upload a version, and the
merchant must accept the update. With an online token, the person may lack
it even when your app has it.

## Answered by

HTTP 403, from:

* [`DELETE /collections/{id}`](/api-reference/admin/collections/delete-a-collection)
* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`DELETE /offers/{id}`](/api-reference/admin/offers/delete-or-archive-an-offer)
* [`GET /bulk/exports`](/api-reference/admin/bulk-exports/list-the-installations-exports)
* [`GET /bulk/exports/{id}`](/api-reference/admin/bulk-exports/get-an-export)
* [`GET /cancel-reasons`](/api-reference/admin/orders/the-merchants-cancel-reasons)
* [`GET /collections`](/api-reference/admin/collections/list-collections)
* [`GET /collections/{id}`](/api-reference/admin/collections/get-a-collection)
* [`GET /customers`](/api-reference/admin/customers/list-customers)
* [`GET /customers/{id}`](/api-reference/admin/customers/get-a-customer)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/get-a-value)
* [`GET /delivery-agents`](/api-reference/admin/delivery/list-delivery-agents)
* [`GET /delivery-agents/{id}`](/api-reference/admin/delivery/get-a-delivery-agent)
* [`GET /delivery-fee-groups`](/api-reference/admin/delivery/list-delivery-fee-groups)
* [`GET /delivery-fee-groups/{id}`](/api-reference/admin/delivery/get-a-delivery-fee-group)
* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`GET /offers`](/api-reference/admin/offers/list-offers)
* [`GET /offers/{id}`](/api-reference/admin/offers/get-an-offer)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`GET /orders`](/api-reference/admin/orders/list-orders)
* [`GET /orders/{id}`](/api-reference/admin/orders/get-an-order)
* [`GET /orders/{id}/comments`](/api-reference/admin/orders/list-an-orders-comments)
* [`GET /products`](/api-reference/admin/products/list-products)
* [`GET /products/{id}`](/api-reference/admin/products/get-a-product)
* [`GET /stores`](/api-reference/admin/stores/list-stores)
* [`GET /stores/{id}`](/api-reference/admin/stores/get-a-store)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PLAN_FEATURE_REQUIRED
Source: https://developers.tassyir.io/errors/plan-feature-required

HTTP 403, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/plan-feature-required`; its `title`: Not included in the merchant's plan.

## What to do

HTTP 403. The merchant's plan lacks the feature (`feature`), such as stock at a
chosen location. Do without it, or tell the merchant.

The answer's `fix`: The merchant's plan does not include this feature; it works once the merchant upgrades.

## Answered by

HTTP 403, from:

* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PLAN_LIMIT_REACHED
Source: https://developers.tassyir.io/errors/plan-limit-reached

HTTP 403, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/plan-limit-reached`; its `title`: Merchant's plan limit reached.

## What to do

The merchant's plan limit is reached; it works once the merchant upgrades or frees capacity.

## Answered by

HTTP 403, from:

* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_DEFAULT_VARIANT
Source: https://developers.tassyir.io/errors/product-default-variant

HTTP 409, from PATCH /products/{id}/variants/{variantId}.

Its problem `type`: `https://developers.tassyir.io/errors/product-default-variant`; its `title`: Default variant follows its product.

## What to do

Change the product's own fields with PATCH /products/\{id}; its default variant follows them.

## Answered by

HTTP 409, from:

* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_DUPLICATE_NAME
Source: https://developers.tassyir.io/errors/product-option-duplicate-name

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-duplicate-name`; its `title`: Bad request.

## What to do

Give each option a different name (case and surrounding spaces are ignored when comparing).

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_DUPLICATE_VALUE
Source: https://developers.tassyir.io/errors/product-option-duplicate-value

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-duplicate-value`; its `title`: Bad request.

## What to do

List each value of an option once (case and surrounding spaces are ignored when comparing).

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_NO_VALUES
Source: https://developers.tassyir.io/errors/product-option-no-values

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-no-values`; its `title`: Bad request.

## What to do

Give every option at least one value that is not empty.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_NOT_FOUND
Source: https://developers.tassyir.io/errors/product-option-not-found

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-not-found`; its `title`: Bad request.

## What to do

Name in a variant's options only options the product has, spelled as in options.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_VALUE_EMPTY
Source: https://developers.tassyir.io/errors/product-option-value-empty

HTTP 400, from PATCH /products/{id}.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-value-empty`; its `title`: Bad request.

## What to do

Remove the empty value: every option value needs at least one visible character.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTION_VALUE_NOT_FOUND
Source: https://developers.tassyir.io/errors/product-option-value-not-found

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-option-value-not-found`; its `title`: Bad request.

## What to do

Select in each variant only values its option lists in options.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_OPTIONS_REQUIRE_VARIANTS
Source: https://developers.tassyir.io/errors/product-options-require-variants

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-options-require-variants`; its `title`: Bad request.

## What to do

Send variants with the options: one for each combination of their values.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_SLUG_INVALID
Source: https://developers.tassyir.io/errors/product-slug-invalid

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-slug-invalid`; its `title`: Bad request.

## What to do

Send a slug with at least one letter that is not a reserved word, or leave it out to derive it from the name.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_SLUG_TAKEN
Source: https://developers.tassyir.io/errors/product-slug-taken

HTTP 409, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-slug-taken`; its `title`: Conflict.

## What to do

Send another slug, or leave it out: another product of this store already uses this one.

## Answered by

HTTP 409, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_COMBINATION_MISMATCH
Source: https://developers.tassyir.io/errors/product-variant-combination-mismatch

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-combination-mismatch`; its `title`: Bad request.

## What to do

Send exactly one variant for each combination of option values, none twice.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_COUNT_MISMATCH
Source: https://developers.tassyir.io/errors/product-variant-count-mismatch

HTTP 400, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-count-mismatch`; its `title`: Bad request.

## What to do

Send one variant per combination of option values: as many variants as the product of the options' value counts.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_DUPLICATE_COMBINATION
Source: https://developers.tassyir.io/errors/product-variant-duplicate-combination

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-duplicate-combination`; its `title`: Bad request.

## What to do

Give each variant a different combination of option values.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_DUPLICATE_OPTION
Source: https://developers.tassyir.io/errors/product-variant-duplicate-option

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-duplicate-option`; its `title`: Bad request.

## What to do

Name each option once in a variant's options.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_INVALID_VALUE
Source: https://developers.tassyir.io/errors/product-variant-invalid-value

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-invalid-value`; its `title`: Bad request.

## What to do

Select for each option one of the values it lists in options.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_MISSING_COMBINATIONS
Source: https://developers.tassyir.io/errors/product-variant-missing-combinations

HTTP 400, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-missing-combinations`; its `title`: Bad request.

## What to do

Add a variant for every combination of option values that has none.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_MISSING_OPTION
Source: https://developers.tassyir.io/errors/product-variant-missing-option

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-missing-option`; its `title`: Bad request.

## What to do

Select a value of every option in each variant, none left out.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_SELECTED_COUNT
Source: https://developers.tassyir.io/errors/product-variant-selected-count

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-selected-count`; its `title`: Bad request.

## What to do

Select exactly one value of every option in each variant.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_VARIANT_UNKNOWN_OPTION
Source: https://developers.tassyir.io/errors/product-variant-unknown-option

HTTP 400, from 2 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-variant-unknown-option`; its `title`: Bad request.

## What to do

Name in a variant's options only options the product has.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# PRODUCT_WRITE_TIMEOUT
Source: https://developers.tassyir.io/errors/product-write-timeout

HTTP 400, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/product-write-timeout`; its `title`: Bad request.

## What to do

Nothing was saved: retry the same request, and if it times out again, save fewer options or values at once.

## Answered by

HTTP 400, from:

* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /products`](/api-reference/admin/products/create-a-product)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# RATE_LIMITED
Source: https://developers.tassyir.io/errors/rate-limited

HTTP 429, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/rate-limited`; its `title`: Rate limit exceeded.

## What to do

HTTP 429. Your installation's bucket is empty. Wait `Retry-After` seconds, then
retry; spread your calls using the `RateLimit-*` headers.

The answer's `fix`: Wait the number of seconds in Retry-After, then retry; keep an eye on RateLimit-Remaining to spread requests.

## Answered by

Every operation of the Admin API, with HTTP 429.

Also the code of a refusal with HTTP 429 that carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# REQUEST_FAILED
Source: https://developers.tassyir.io/errors/request-failed

A 4xx refusal with a status other than 400, 401, 403, 404, 405, 409, 413, 415, 422, 429 or 460, when it carries no more specific code.

Its problem `type`: `https://developers.tassyir.io/errors/request-failed`; its `title`: Request failed.

## What to do

Act on the status and the detail; if they do not say enough, report the requestId to Tassyir.

## Answered by

The code of a 4xx refusal with a status other than 400, 401, 403, 404, 405, 409, 413, 415, 422, 429 or 460, when it carries no more specific code. Any operation may answer it.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# RESPONSE_TOO_LARGE
Source: https://developers.tassyir.io/errors/response-too-large

HTTP 502, from a hosted app's TASSYIR binding, before the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/response-too-large`; its `title`: Response too large.

## What to do

HTTP 502. The API's answer was larger than a hosted app may receive (8 MiB).
Ask for less: a smaller `limit`, or `?fields=` with only the fields you read.

## Answered by

A hosted app's `ctx.props.TASSYIR` binding answers it itself, before the call reaches the Admin API, so the problem has no `requestId` and the API's reference does not list it. How the binding calls the API: [Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# SERVICE_UNAVAILABLE
Source: https://developers.tassyir.io/errors/service-unavailable

HTTP 503, from every operation of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/service-unavailable`; its `title`: Service unavailable.

## What to do

HTTP 503. Something Tassyir depends on is down. Retry with backoff, writes with the
same `Idempotency-Key`.

The answer's `fix`: Retry with exponential backoff.

## Answered by

Every operation of the Admin API, with HTTP 503.

Also the code of a refusal with HTTP 503 that carries no more specific code.

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# STORE_REQUIRED
Source: https://developers.tassyir.io/errors/store-required

HTTP 400, from POST /orders.

Its problem `type`: `https://developers.tassyir.io/errors/store-required`; its `title`: Bad request.

## What to do

Name the store with storeId: this installation acts in several stores.

## Answered by

HTTP 400, from:

* [`POST /orders`](/api-reference/admin/orders/create-an-order)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# STORE_SCOPE_FORBIDDEN
Source: https://developers.tassyir.io/errors/store-scope-forbidden

HTTP 460, from 17 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/store-scope-forbidden`; its `title`: Store not accessible.

## What to do

HTTP 460. Your request named a store (`storeId`) outside the stores the
merchant gave your installation. Use one of its stores; list them with
`GET /stores` (`read_stores`).

The answer's `fix`: Only name stores this installation may access; the merchant chooses them when installing the app.

## Answered by

HTTP 460, from:

* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`GET /collections`](/api-reference/admin/collections/list-collections)
* [`GET /customers`](/api-reference/admin/customers/list-customers)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/get-a-value)
* [`GET /delivery-fee-groups`](/api-reference/admin/delivery/list-delivery-fee-groups)
* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /offers`](/api-reference/admin/offers/list-offers)
* [`GET /orders`](/api-reference/admin/orders/list-orders)
* [`GET /products`](/api-reference/admin/products/list-products)
* [`GET /stores/{id}`](/api-reference/admin/stores/get-a-store)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a refusal with HTTP 460 that carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# SUBSCRIPTION_REQUIRED
Source: https://developers.tassyir.io/errors/subscription-required

HTTP 422, from 3 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/subscription-required`; its `title`: Unprocessable request.

## What to do

HTTP 422. The route needs a plan, and the business has no usable subscription.
Tell the merchant.

The answer's `fix`: Do not retry until the merchant subscribes again: this needs a subscription the business does not have.

## Answered by

HTTP 422, from:

* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# TASSYIR_BINDING_NOT_AVAILABLE
Source: https://developers.tassyir.io/errors/tassyir-binding-not-available

HTTP 503, from a hosted app's TASSYIR binding, before the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/tassyir-binding-not-available`; its `title`: Not available.

## What to do

HTTP 503. Calls to the Admin API from a hosted app are not available right
now; nothing was sent. Try again later.

## Answered by

A hosted app's `ctx.props.TASSYIR` binding answers it itself, before the call reaches the Admin API, so the problem has no `requestId` and the API's reference does not list it. How the binding calls the API: [Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# UNAUTHORIZED
Source: https://developers.tassyir.io/errors/unauthorized

A refusal with HTTP 401 that carries no more specific code.

Its problem `type`: `https://developers.tassyir.io/errors/unauthorized`; its `title`: Unauthorized.

## What to do

Send a valid access token as Authorization: Bearer tsy\_at\_…; get a new one from POST /apps/oauth/token.

## Answered by

The code of a refusal with HTTP 401 that carries no more specific code. Any operation may answer it.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# UNPROCESSABLE_ENTITY
Source: https://developers.tassyir.io/errors/unprocessable-entity

A refusal with HTTP 422 that carries no more specific code.

Its problem `type`: `https://developers.tassyir.io/errors/unprocessable-entity`; its `title`: Unprocessable request.

## What to do

Correct the request as the detail says; the same request fails the same way.

## Answered by

The code of a refusal with HTTP 422 that carries no more specific code. Any operation may answer it.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# UNSUPPORTED_MEDIA_TYPE
Source: https://developers.tassyir.io/errors/unsupported-media-type

HTTP 415, from 22 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/unsupported-media-type`; its `title`: Unsupported media type.

## What to do

Send the body as JSON, with Content-Type: application/json in UTF-8.

## Answered by

HTTP 415, from:

* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a refusal with HTTP 415 that carries no more specific code.

A hosted app's `ctx.props.TASSYIR` binding also answers it itself, before the call is sent ([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# VALIDATION_FAILED
Source: https://developers.tassyir.io/errors/validation-failed

HTTP 400, from 53 operations of the Admin API.

Its problem `type`: `https://developers.tassyir.io/errors/validation-failed`; its `title`: Invalid request.

## What to do

HTTP 400. A parameter or a field failed validation, or is not one the route
takes. `errors` lists each problem. Fix the request: unknown parameters are
refused on purpose, so a misspelt filter never silently returns everything.

The answer's `fix`: Correct the parameters listed in errors, then retry.

## Answered by

HTTP 400, from:

* [`DELETE /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/delete-a-value)
* [`GET /bulk/exports`](/api-reference/admin/bulk-exports/list-the-installations-exports)
* [`GET /bulk/exports/{id}`](/api-reference/admin/bulk-exports/get-an-export)
* [`GET /business`](/api-reference/admin/business/the-business-the-app-is-installed-on)
* [`GET /cancel-reasons`](/api-reference/admin/orders/the-merchants-cancel-reasons)
* [`GET /collections`](/api-reference/admin/collections/list-collections)
* [`GET /collections/{id}`](/api-reference/admin/collections/get-a-collection)
* [`GET /customers`](/api-reference/admin/customers/list-customers)
* [`GET /customers/{id}`](/api-reference/admin/customers/get-a-customer)
* [`GET /data`](/api-reference/admin/data/list-the-apps-values)
* [`GET /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/get-a-value)
* [`GET /delivery-agents`](/api-reference/admin/delivery/list-delivery-agents)
* [`GET /delivery-agents/{id}`](/api-reference/admin/delivery/get-a-delivery-agent)
* [`GET /delivery-fee-groups`](/api-reference/admin/delivery/list-delivery-fee-groups)
* [`GET /delivery-fee-groups/{id}`](/api-reference/admin/delivery/get-a-delivery-fee-group)
* [`GET /inventory-levels`](/api-reference/admin/inventory/list-stock-levels)
* [`GET /inventory-levels/{id}`](/api-reference/admin/inventory/get-a-stock-level)
* [`GET /offers`](/api-reference/admin/offers/list-offers)
* [`GET /offers/{id}`](/api-reference/admin/offers/get-an-offer)
* [`GET /offers/{id}/codes`](/api-reference/admin/offers/list-an-offers-codes)
* [`GET /offers/{id}/redemptions`](/api-reference/admin/offers/list-an-offers-redemptions)
* [`GET /orders`](/api-reference/admin/orders/list-orders)
* [`GET /orders/{id}`](/api-reference/admin/orders/get-an-order)
* [`GET /orders/{id}/comments`](/api-reference/admin/orders/list-an-orders-comments)
* [`GET /products`](/api-reference/admin/products/list-products)
* [`GET /products/{id}`](/api-reference/admin/products/get-a-product)
* [`GET /stores`](/api-reference/admin/stores/list-stores)
* [`GET /stores/{id}`](/api-reference/admin/stores/get-a-store)
* [`PATCH /collections/{id}`](/api-reference/admin/collections/update-a-collection)
* [`PATCH /collections/{id}/products`](/api-reference/admin/collections/change-a-collections-members)
* [`PATCH /offers/{id}`](/api-reference/admin/offers/update-an-offer)
* [`PATCH /orders/{id}`](/api-reference/admin/orders/update-an-order)
* [`PATCH /products/{id}`](/api-reference/admin/products/update-a-product)
* [`PATCH /products/{id}/variants/{variantId}`](/api-reference/admin/products/update-one-variants-fields)
* [`POST /bulk/exports`](/api-reference/admin/bulk-exports/export-a-whole-list)
* [`POST /collections`](/api-reference/admin/collections/create-a-collection)
* [`POST /images`](/api-reference/admin/images/upload-an-image-from-an-address)
* [`POST /inventory-levels/{id}/adjust`](/api-reference/admin/inventory/correct-a-stock-count)
* [`POST /offers`](/api-reference/admin/offers/create-an-offer)
* [`POST /offers/{id}/codes`](/api-reference/admin/offers/add-a-code-to-an-offer)
* [`POST /offers/{id}/codes/bulk`](/api-reference/admin/offers/add-up-to-250-codes-to-an-offer)
* [`POST /offers/{id}/codes/{codeId}/disable`](/api-reference/admin/offers/disable-a-code)
* [`POST /offers/{id}/codes/{codeId}/enable`](/api-reference/admin/offers/enable-a-disabled-code)
* [`POST /offers/{id}/pause`](/api-reference/admin/offers/pause-an-offer)
* [`POST /offers/{id}/publish`](/api-reference/admin/offers/publish-an-offer)
* [`POST /offers/{id}/resume`](/api-reference/admin/offers/resume-a-paused-offer)
* [`POST /orders`](/api-reference/admin/orders/create-an-order)
* [`POST /orders/{id}/cancel`](/api-reference/admin/orders/cancel-an-order)
* [`POST /orders/{id}/comments`](/api-reference/admin/orders/comment-on-an-order)
* [`POST /orders/{id}/confirm`](/api-reference/admin/orders/confirm-an-order)
* [`POST /orders/{id}/schedule`](/api-reference/admin/orders/schedule-a-call-back)
* [`POST /products`](/api-reference/admin/products/create-a-product)
* [`PUT /data/{ownerType}/{ownerId}/{key}`](/api-reference/admin/data/write-a-value)

Also the code of a 400 refusal that lists its invalid parameters, when it carries no more specific code.

The shape of every problem, and how `@tassyir/app` reports it: [Errors](/guides/errors).


# Admin API conventions
Source: https://developers.tassyir.io/guides/admin-api

How every Admin API route behaves, from versions, money and cursors to idempotent writes, errors and rate limits.

The Admin API is the versioned REST API your app calls to read and change a
business. Every route follows the conventions on this page, so learn them
once: how lists page, how a write is made safe to retry, how errors read and
how fast you may call.

## Calling it

`https://api.tassyir.io/apps/2026-10/<resource>`, with an access token:

```bash theme={null}
curl https://api.tassyir.io/apps/2026-10/business \
  -H "Authorization: Bearer $TASSYIR_ACCESS_TOKEN"
```

```json theme={null}
{
  "data": {
    "id": "741939488313319175",
    "name": "Dar Amina",
    "currency": "DZD",
    "country": "DZ",
    "timezone": "Africa/Algiers",
    "createdAt": "2026-01-02T03:04:05.000Z"
  }
}
```

The business comes from the token: no route takes a business id.
`GET /business` needs no scope; every other route needs the scope its guide
names. With `@tassyir/app`, paths are relative to `/apps/2026-10`, and paths,
parameters, bodies and answers are typed:

```ts theme={null}
const { data: business } = await admin.get('/business');
const { data: order } = await admin.get('/orders/{id}', {
  path: { id: '741000000000000001' },
  query: { fields: ['orderNumber', 'status', 'total', 'currency'] },
});
console.log(business.timezone, order.status, order.total);
```

| Resource | Guide |
| - | - |
| `orders`, `cancel-reasons` | [Orders](/guides/orders) |
| `products`, `collections`, `images` | [Products and collections](/guides/products-and-collections) |
| `inventory-levels` | [Stock](/guides/stock) |
| `customers` | [Customers and contact data](/guides/customers) |
| `offers` | [Offers](/guides/offers), [Write offers and codes](/guides/write-offers) |
| `stores`, `delivery-agents`, `delivery-fee-groups` | [Stores and delivery](/guides/stores-and-delivery) |
| `data` | [App data](/guides/app-data) |

## Versions

The version is in the path: `2026-10` is the first and, today, the only one.
Within a version, fields may be added, never renamed, retyped or removed, so
ignore fields you do not know. A version that does not exist answers 404.

Versions are released quarterly and supported for 12 months. Tassyir emails
you 90 days before a version you use is retired; once it is, its requests are
answered by the oldest supported version, with the headers
`Tassyir-Api-Version-Served` and `Deprecation`.

## Values

* JSON fields are **camelCase**. Ids are **strings**: never parse them as
  numbers. Times are ISO 8601 in UTC (`2026-10-11T09:12:44.120Z`).
* **Money is a decimal string** with two decimals (`"2500.00"`) next to a
  `currency` field (`DZD` today), never a number. Keep it a string; for
  arithmetic, use a decimal library or integer cents, never `parseFloat`. An
  amount Tassyir does not know is `null`, never `"0.00"`. When you send money
  (a product's price), send a decimal string too.
* Open vocabularies (an order's `status`, a carrier's status) are strings,
  not enums: a merchant or a carrier can add values.
* **Contact fields** (a buyer's name, phones, email, address, an order's
  notes) are present only with `read_customer_contact`. Without it the keys
  are **absent**, not `null` ([Customers and contact data](/guides/customers)).

## One resource, and lists

A single resource is `{ "data": { … } }`. A list is
`{ "data": [ … ], "nextCursor": "…" | null }`:

| Parameter | Rule |
| - | - |
| `limit` | 1 to 100, default 50. Anything else is 400 `VALIDATION_FAILED`, never clamped. |
| `cursor` | The previous page's `nextCursor`, unchanged. Omit it for the first page. |
| `fields` | Trims each item ([below](#fields)). |

* Lists are **newest first** and **keyset-paged**: a row added while you walk
  a list never shifts the pages to come, and no row is repeated or skipped.
  New rows appear on a new walk from the first page.
* `nextCursor` is **opaque**: never build or edit one. It belongs to its list
  and its filters; with another list or other filters it is 400
  `INVALID_CURSOR`. `nextCursor: null` is the last page.
* A page can hold fewer than `limit` items while `nextCursor` is set (app data
  drops values whose owner you can no longer read). Stop on `null`, not on a
  short page.
* **Unknown parameters are refused** (400 `VALIDATION_FAILED`, naming them): a
  misspelt filter never silently returns everything.

`admin.paginate` walks every page for you:

```ts theme={null}
let pending = 0;
for await (const order of admin.paginate('/orders', {
  query: { status: 'pending', limit: 100, fields: ['id'] },
})) {
  pending += 1;
}
console.log(`${pending} pending orders`);
```

## Fields

`?fields=status,total,buyer` trims each resource to the named **top-level**
fields; `id` is always kept. An unknown name is 400 `INVALID_FIELDS`, with the
`allowedFields`. Trimming happens after masking: naming a field your
installation may not read returns nothing for it. With the SDK, `fields` is a
typed list: `fields: ['status', 'total']`.

## Idempotent writes

Every write (`POST`, `PUT`, `PATCH`, `DELETE`) accepts an `Idempotency-Key`
header: 1 to 255 visible ASCII characters, usually a UUID. Send one, and a
retry of the same write never runs it twice. Keys belong to your
installation and are kept 24 hours.

| Situation | Answer |
| - | - |
| First use | The write runs. A success is stored for 24 hours; a failure is not, so you can retry. |
| Same key, same method, path, query and body | The stored answer and status, with `Idempotent-Replayed: true`. Nothing runs again. |
| Same key, anything else different | 422 `IDEMPOTENCY_KEY_REUSED` |
| Same key while the first request still runs | 409 `IDEMPOTENCY_KEY_IN_USE` (a key whose request died is freed within 100 seconds) |
| A malformed key | 400 `IDEMPOTENCY_KEY_INVALID` |
| Tassyir cannot check keys right now | 503 `IDEMPOTENCY_UNAVAILABLE`, with `Retry-After`. The write was **not** attempted. |

`@tassyir/app` sends a new key with every write and reuses it for its own
retries. Pass your own when a retry may come from elsewhere (a job that can
run twice), or `false` to send none:

```ts theme={null}
await admin.post('/orders/{id}/confirm', {
  path: { id: '741000000000000001' },
  idempotencyKey: 'confirm-741000000000000001',
});
```

## Errors

Every error under `/apps/2026-10/` is `application/problem+json`
([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)):

```json theme={null}
{
  "type": "https://developers.tassyir.io/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "You do not have permission: orders:read",
  "code": "PERMISSION_DENIED",
  "permission": "orders:read",
  "fix": "Request the read_orders scope in the app's manifest; it applies once the merchant consents to the new version.",
  "requestId": "a1b2c3"
}
```

* **Act on `code`**, never on `detail` or `title`: `code` is stable.
* **`fix`** is one sentence saying what to do, when there is one.
* Other members name what was refused: `permission`, `storeId`, `limit`,
  `errors`, `allowedFields`, …
* **`requestId`** (also the `X-Request-Id` header) names the request: quote it
  when you ask Tassyir for help.
* A 5xx never carries an internal message: retry with backoff.

`@tassyir/app` turns a problem into a `TassyirApiError`, with `code`, `fix`,
`status`, `requestId`, `retryAfterSeconds` and the whole `problem`. The codes
each call can answer are typed:

```ts theme={null}
import { TassyirApiError, type AdminApiErrorCode } from '@tassyir/app';

type ConfirmError = AdminApiErrorCode<'post', '/orders/{id}/confirm'>;

export async function confirm(
  id: string,
): Promise<'confirmed' | 'waiting' | ConfirmError> {
  try {
    await admin.post('/orders/{id}/confirm', { path: { id } });
    return 'confirmed';
  } catch (error) {
    if (!(error instanceof TassyirApiError)) throw error;
    if (error.code === 'ORDER_LIMIT_REACHED') return 'waiting'; // past the plan's allowance
    console.warn(error.code, error.fix, error.requestId);
    return error.code as ConfirmError;
  }
}
```

[Errors](/guides/errors) lists every code, with what to do about the common ones.
The token endpoint is the one exception: it answers OAuth errors
([Tokens](/guides/tokens#the-token-endpoint-without-the-sdk)).

### Stores: 460, and 404

An installation reaches only the stores its merchant gave it. A store your
request names (a `storeId` filter or field) outside them is **HTTP 460
`STORE_SCOPE_FORBIDDEN`**. A resource of another store, named by its id,
reads as **404 `NOT_FOUND`**: the API never says it exists.

## Rate limits

Every answer carries your installation's bucket:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | The bucket's size |
| `RateLimit-Remaining` | Requests accepted right now |
| `RateLimit-Reset` | Seconds until the bucket is full again |

* **Your installation's bucket**: by default 40 requests at once, refilled at
  4 a second. Past it: **429 `RATE_LIMITED`**, with `Retry-After` (seconds
  until one more request fits). Online and offline tokens of an installation
  share one bucket.
* **The business's ceiling**: all the apps of one business share, by
  default, 20 requests at once and 20 a second. Past it: **429
  `BUSINESS_RATE_LIMITED`**, with `Retry-After`; then other apps of the
  business are using the room, so spread your calls out.
* **A busy API**: when the API is already running its maximum of app
  requests, it answers **503 `API_BUSY`** with `Retry-After: 1`, having done
  **nothing**: any call, a write included, can be retried as it was.
* Image uploads have their own daily quota
  ([Products and collections](/guides/products-and-collections#limits)).

The numbers are defaults Tassyir may tune: read the headers rather than
hard-coding them. Retries are off by default in `@tassyir/app`; with
`retries: 3` it waits `Retry-After` and retries 429 and 503 `API_BUSY` (writes
included), any other 503, network errors, 502 and 504 for calls safe to
repeat (reads, and writes with a key), and 500 for reads only.

## Plans

No plan is needed to install an app or call the API. A plan's limits still
apply to what your app does, as they apply to the merchant: the service
refuses with the code the dashboard would show (`PLAN_FEATURE_REQUIRED`,
`ORDER_LIMIT_REACHED`, `SUBSCRIPTION_REQUIRED`).

## Masking

* Without `read_customer_contact`, contact fields are absent.
* When the merchant's plan hides phones (no active subscription, or a billing
  grace that hides them), phones read `**********`.
* A **waiting** order (past the plan's order allowance, `waiting: true`) is
  masked whatever your scopes: phones `**********` and notes `null`, until it
  unlocks (`orders/updated` with `waiting`).

## Caching

Every answer is `Cache-Control: no-store`: it is a merchant's private data.
Cache only what your app needs, and drop it on `app/uninstalled`.


# App data
Source: https://developers.tassyir.io/guides/app-data

Keep your app's values in Tassyir, next to the business, its stores, products, orders and customers, under keys your manifest declares.

Your app often needs to remember something about a merchant's resource: a
product's review rating, an order's sync state with another system, a
customer's loyalty points, a setting for the whole business. App data keeps
those values in Tassyir, next to the resource, so your app needs no database
of its own for them.

## Declare the keys

Every key is declared in the manifest:

```toml theme={null}
[[data.definitions]]
owner      = "product"   # business | store | product | order | customer
key        = "rating"    # [a-z][a-z0-9_]{0,63}, unique per owner
type       = "json"      # string | number | integer | boolean | json
visibility = "app"       # app | merchant | storefront
```

* **The installation's version decides.** A key your new version adds can be
  written on an installation only once its merchant accepts that version.
* **The type is checked on every write.** The visibility comes from the
  declaration, never from the request.
* `visibility`: `app` values are read by your app only. `merchant` values
  are meant for the dashboard and `storefront` values for the store's pages;
  neither is shown there yet, so declare them only for values you would be
  happy to see shown.
* **A key a newer version drops** keeps its values: still readable
  (`declared: false`) and deletable, never writable. A key whose type changes
  keeps its old values; the next write must match the new type.

## Owners and scopes

Reading or writing a value needs the scope that reads its owner. Writing a
value changes nothing about the owner, so no `write_*` scope is needed.

| Owner | Scope | Owner id |
| - | - | - |
| `business` | none | the installation's business |
| `store` | `read_stores` | a store |
| `product` | `read_products` | a product |
| `order` | `read_orders` | an order |
| `customer` | `read_customers` | a customer |

The owner is read first, as `GET /products/{id}` (or the others) would read
it: an owner your token cannot read is 404 `NOT_FOUND`, a store outside your
installation's is 460. So an online token never touches a value about
something its person cannot see.

## Write, read, delete

```ts theme={null}
const owner = {
  ownerType: 'product',
  ownerId: '741000000000000500',
  key: 'rating',
} as const;

// PUT writes the whole value: 201 when it is new, 200 when it replaced one.
await admin.put('/data/{ownerType}/{ownerId}/{key}', {
  path: owner,
  body: { value: { average: 4.5, count: 12 } },
});

const { data: rating } = await admin.get('/data/{ownerType}/{ownerId}/{key}', {
  path: owner,
});
console.log(rating.value, rating.visibility, rating.updatedAt);

await admin.delete('/data/{ownerType}/{ownerId}/{key}', { path: owner });
```

```json theme={null}
{
  "id": "9500000000000000001",
  "ownerType": "product",
  "ownerId": "741000000000000500",
  "key": "rating",
  "value": { "average": 4.5, "count": 12 },
  "visibility": "app",
  "declared": true,
  "createdAt": "2026-10-14T08:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

* The body is `{ "value": … }` and nothing else. A value is never `null`:
  remove one with `DELETE`.
* A missing value answers 404 `NOT_FOUND` (its `detail` says whether the
  owner or the value is missing).
* `GET /data` lists your installation's values, newest first. Filters:
  `ownerType`, `ownerId` (with `ownerType`), `key`. Values whose owner you can
  no longer read are left out, so **a page can be shorter than `limit` while
  `nextCursor` is set**: keep reading until it is `null`.

```ts theme={null}
for await (const value of admin.paginate('/data', {
  query: { ownerType: 'product', key: 'rating' },
})) {
  console.log(value.ownerId, value.value);
}
```

## Values

| Type | Accepted |
| - | - |
| `string` | a JSON string |
| `number` | a finite JSON number |
| `integer` | a safe integer, -(2^53 - 1) to 2^53 - 1 |
| `boolean` | `true` or `false` |
| `json` | any JSON value: an object, array, string, number or boolean |

* At most **16,384 bytes** of compact JSON in UTF-8 (an Arabic letter is two
  bytes): 400 `APP_DATA_VALUE_TOO_LARGE`.
* Refused with 400 `APP_DATA_VALUE_INVALID` and a `reason`: `wrong_type`,
  `not_finite`, `nul_character`, `lone_surrogate`, `reserved_key` (an object
  key `__proto__`, `constructor` or `prototype`), `too_deep` (more than 32
  levels).
* An object's keys come back in the order Tassyir stores them (shorter
  keys first), not the order you sent.
* A key the version does not declare for that owner is 400
  `APP_DATA_KEY_NOT_DECLARED`.

## Limits

An installation holds at most **50,000 values**, whatever their owners.
Writing a new key past that is 409 `APP_DATA_LIMIT_REACHED` (`limit`,
`used`); rewriting a value that exists is never refused, and `DELETE` frees a
slot. Values of keys a version dropped count until you delete them.

## When values go away

* Values stay when their owner is deleted, until you delete them; they drop
  out of lists and reads.
* When the merchant uninstalls your app, its values are deleted 48 hours
  later, and your app receives `business/redact`. A reinstall, even within
  those 48 hours, is a new installation that starts empty, and an uninstalled
  installation can no longer read its values: if a value must survive a
  reinstall, keep your own copy
  ([Compliance and uninstall](/guides/compliance-and-uninstall)).


# Compliance and uninstall
Source: https://developers.tassyir.io/guides/compliance-and-uninstall

What happens when a merchant uninstalls your app, and how to honour buyer data requests and the deletion that follows an uninstall.

A merchant can uninstall your app at any time, and buyers can ask for their
data to be exported or erased. Tassyir tells your app through webhooks, and
your app must do its part: stop using the business's data, and delete or
export what it holds.

## Subscribe to the compliance topics

```toml theme={null}
[[webhooks]]
topics = ["app/uninstalled", "customers/data_request", "customers/redact", "business/redact"]
uri    = "/webhooks"
```

The compliance topics need no scope. A custom app is not required to
subscribe to them; an app in the marketplace is (the review checks it:
[Publishing to the marketplace](/guides/publishing#the-review-checklist)). Subscribe anyway
if your app keeps any data about a business or its buyers: Tassyir deletes
the data it holds for your app either way, but only your app can delete what
your servers hold.

## Uninstall

When a merchant uninstalls your app:

1. **Every token is revoked at once.** The next Admin API call is 401
   `APP_TOKEN_INVALID`, and a refresh is refused.
2. **`app/uninstalled`** is sent to that installation (`data.installation`,
   with `status: "uninstalled"` and `uninstalledAt`). Forget its tokens, stop
   its jobs, and stop calling the API for it.
3. **48 hours later**, Tassyir deletes every [app data](/guides/app-data) value
   the installation kept, and sends **`business/redact`** to that installation
   (`data.business.id`). Delete everything your servers still hold about the
   business for it.

On [Tassyir Hosting](/guides/tassyir-hosting#webhooks), the installation's own
database (`ctx.props.STORAGE`) is deleted with its app data, and both
deliveries reach your code with `ctx.props.TASSYIR` refused
(`HOSTED_CALL_REFUSED`).

```ts theme={null}
import type { VerifiedWebhook } from '@tassyir/app';

// Called with a verified delivery (see Webhooks).
export async function onLifecycle(delivery: VerifiedWebhook): Promise<void> {
  switch (delivery.event.type) {
    case 'app/uninstalled':
      await tassyir.tokens.forget(delivery.installationId);
      // Stop scheduled work for this installation.
      break;
    case 'business/redact':
      // Delete what you keep for this installation of delivery.businessId.
      break;
  }
}
```

[Webhooks](/guides/webhooks#verify-every-delivery) shows how to verify a delivery.

* A **reinstall** is a new installation, with a new id, a new consent and no
  data, even within the 48 hours. The old installation's `business/redact`
  still comes, naming the old installation id: delete by installation, not
  by business.
* `business/redact` reaches only the uninstalled installation it names, and
  is redelivered like any webhook: answer 200 when you already handled it,
  even though the installation is gone.

## Buyer data requests

`customers/data_request` and `customers/redact` are sent when Tassyir exports
or erases a buyer's data for a business.

```json theme={null}
{
  "id": "evt_741000000000000002",
  "type": "customers/redact",
  "apiVersion": "2026-10",
  "createdAt": "2026-10-12T10:00:00.000Z",
  "businessId": "632000000000000001",
  "storeId": null,
  "appId": "741000000000000900",
  "installationId": "755000000000000001",
  "changed": [],
  "data": {
    "customer": { "id": "741000000000001000", "phone": "+213555123456" },
    "orderIds": ["741000000000000001", "741000000000000002"]
  }
}
```

* `data.customer.id` is the customer ([Customers](/guides/customers));
  `data.customer.phone` is there only with `read_customer_contact`, and reads
  `**********` when the plan hides phones or when every order it names was
  waiting. `data.orderIds` are the buyer's orders your installation could
  see.
* An installation limited to selected stores is told only about orders in its
  stores, and gets no delivery when none is left: it never saw this buyer.
* **`customers/redact`**: delete or anonymise everything your app holds about
  that buyer and those orders. Tassyir has already erased the buyer from the
  orders; the orders themselves stay, as the merchant's records.
* **`customers/data_request`**: gather what your app holds about that buyer
  and make it available to the merchant.

These bodies are built from what Tassyir recorded when the request was made,
so a replay within 7 days carries the same buyer even though the data is
gone.

## Suspension

Tassyir can suspend an installation, or a whole app. Its tokens are revoked,
its page cannot be opened, and its webhooks are skipped until it is resumed.

## A checklist

* Subscribe to `app/uninstalled`, `customers/data_request`,
  `customers/redact` and `business/redact`.
* On `app/uninstalled`: forget the tokens and stop the installation's work.
* On `customers/redact`: erase the buyer from your systems.
* On `customers/data_request`: be able to tell the merchant what you hold.
* On `business/redact`: delete what you hold for that installation.
* Deduplicate on `webhook-id`, and answer 2xx to a delivery you already
  handled.


# Customers and contact data
Source: https://developers.tassyir.io/guides/customers

Read buyers and their delivery record, and handle buyers' names, phones and addresses with the read_customer_contact scope.

A customer is a buyer of the business, known by phone number and built from
their orders: they have no account. An app reads customers to see how each
buyer's orders went (a review app skips buyers who returned parcels, a
loyalty app rewards repeat buyers). Buyers' names, phones and addresses are
the most sensitive data a merchant holds, and they have a scope of their own.

| Route | Scope |
| - | - |
| `GET /customers`, `GET /customers/{id}` | `read_customers` (it implies `read_orders`) |
| A buyer's name, phone and address | `read_customer_contact` |

## The customer

```json theme={null}
{
  "id": "741000000000001000",
  "provinceCode": 16,
  "townOns": 1601,
  "name": "Amina B.",
  "phone": "0555123456",
  "ordersCount": 5,
  "openCount": 1,
  "deliveredCount": 3,
  "returnedCount": 1,
  "canceledCount": 0,
  "currency": "DZD",
  "deliveredValue": "11700.75",
  "firstOrderAt": "2026-06-01T10:00:00.000Z",
  "lastOrderAt": "2026-10-11T07:00:00.000Z",
  "blocked": false,
  "createdAt": "2026-09-26T00:00:00.000Z",
  "updatedAt": "2026-10-11T07:00:20.000Z"
}
```

* **The delivery record is always there:** orders placed (exchanges,
  waiting, archived and abandoned ones left out), open, delivered, returned
  and cancelled; the value of delivered orders (`deliveredValue`, a decimal
  string); the first and last order; whether the merchant blocked the buyer.
* `provinceCode` and `townOns` (the wilaya and commune of their newest order
  that has one) are not contact data.
* **`name` and `phone` need `read_customer_contact`.** A buyer's second phone
  and address are on their orders (`buyer.phone2`, `buyer.address`), under the
  same scope.
* The merchant's private note about a buyer is never sent.
* A customer can be about 20 seconds behind their latest order.

`GET /customers` lists every buyer with at least one counted order, newest
first. `storeId` lists the buyers of one store, **with that store's
counters**. An installation limited to selected stores sees a buyer only
through orders in its stores, and reads those stores' counters summed, never
the whole business's. Search and segments are not offered: page the list,
and follow `customers/updated`.

## `read_customer_contact`

Without it, contact fields are **left out**: the keys are absent, not `null`,
so your app can tell "not granted" from "empty". It covers:

* an order's or checkout's `buyer.name`, `phone`, `phone2`, `email`,
  `address`, `address2`, and the order's `note` and `deliveryNote` (buyers
  type contact details into notes);
* another author's order comments;
* a customer's `name` and `phone`;
* the same fields in webhook bodies, and the customer picker's `name` and
  `phone` ([Embedded pages](/guides/embedded-pages#pickers)).

The scope is marked **sensitive** on the install screen, every Admin API
answer that carries contact fields is logged, and only a member who sees
every order can grant it. It needs `read_orders`.

Even with it:

* **when the merchant's plan hides phones** (no active subscription, or a
  billing grace that hides them), every phone reads `**********`;
* **a waiting order** (past the plan's order allowance) shows
  `**********` for its phones and `null` for its notes and other authors'
  comments, until it unlocks.

```ts theme={null}
const { data: customer } = await admin.get('/customers/{id}', {
  path: { id: '741000000000001000' },
});
if (customer.phone === undefined) {
  console.log('no read_customer_contact: ask for it in a new version');
} else if (/^\*+$/.test(customer.phone)) {
  console.log('the phone is hidden right now');
}
```

## Handle buyer data with care

* Ask for `read_customer_contact` only if your app does something with the
  buyer's contact (sending a message, printing a label). Make it optional
  when only some merchants will want that feature.
* Store as little as you can, for as short as you can, and never in logs.
* Honour `customers/redact` and `customers/data_request`, and delete what you
  hold about a business on `business/redact`
  ([Compliance and uninstall](/guides/compliance-and-uninstall)).


# Dev stores
Source: https://developers.tassyir.io/guides/dev-stores

Build and test on businesses seeded with synthetic data, where nothing reaches a carrier, a buyer or a payment provider.

A dev store is a business you create from the developer console to build and
test apps on. It looks and works like a merchant's business, in the
dashboard and through the Admin API, with synthetic data. Nothing it does
reaches an outside party or costs money, and it needs no subscription.

You own it, so your custom apps install there like on any business you own.

## Create one

In the developer console, open **Dev stores** and create one, with a name and
seed data (the default) or empty.

| Limit | Value |
| - | - |
| Dev stores per developer account | 3, and they cannot be deleted |
| New orders a day (dashboard and API together) | 50, per Algiers day |
| Stores in a dev store | 3 |
| People in a dev store | 5 (invitations are refused) |

## The seed data

* **30 products**, most with options (size, colour, shoe size, volume) and a
  variant per combination. The first 8 track stock (20 to 80 units each).
  No images and no collections.
* **64 buyers**, every one with a phone in the reserved block
  `+213 500 000 000` to `+213 500 000 999`, and no email. Together they cover
  all 58 wilayas.
* **200 orders** over the last 60 days, in every state: pending, incomplete,
  confirmed, scheduled, cancelled, dispatched, delivered, returned, and
  abandoned checkouts. Shipped orders ride a private courier.

Seeding sends no webhook: the data exists before your app is installed. To
see webhooks, change something after installing (create or confirm an order,
edit a product).

## What is switched off

In the dashboard, an action that would reach an outside party is refused
with **409 `DEV_STORE_RESTRICTED`**, naming the `action` it stopped and a
`fix`:

| `action` | What it stops |
| - | - |
| `carrier` | Linking a carrier account, and dispatching to a carrier (use a private courier) |
| `integration` | Connecting other platforms, spreadsheets, ad accounts and conversion tracking |
| `whatsapp` | Connecting a WhatsApp number |
| `email` | Team invitations |
| `billing` | Checkout, plan changes, refunds and credit purchases |
| `ai` | AI images and pages, product imports and scraping |
| `custom_domain` | Adding a custom domain |
| `storefront_checkout` | Orders and checkouts from the storefront |
| `cargo` | Tassyir Cargo |

Through the Admin API, the one refusal particular to dev stores is the daily
order cap: `POST /orders` answers **429 `DEV_STORE_ORDER_LIMIT_REACHED`**,
with `retryAfterSeconds` (until the next Algiers day).

The storefront says it is a development store, takes no orders, is hidden
from search engines and carries no tracking pixel.

**Still on:** webhooks to your app (that is the point), image uploads
(`POST /images`, within a tenth of the usual daily quota), and push
notifications to your own devices.

## The plan

A dev store has every plan feature, with the limits above. It
is never billed, has no order allowance (no order is ever `waiting`) and its
phones are never hidden for want of a subscription. To test what an app does
on a smaller plan, or with waiting orders and hidden phones, use a real
business on that plan.


# Embedded pages and App Bridge
Source: https://developers.tassyir.io/guides/embedded-pages

Show your app's page inside the Tassyir dashboard and use App Bridge for ID tokens, toasts, modals, the save bar, navigation and pickers.

Your app can have a page inside the Tassyir dashboard, next to the merchant's
orders and products. The dashboard shows it in a frame and talks to it
through **App Bridge**: your page asks for ID tokens, shows toasts and
modals, uses the dashboard's save bar and title bar, navigates, and opens the
dashboard's pickers. `@tassyir/app-bridge` is the page's side of it.

## How the page is loaded

Set `admin.page` in the manifest (usually `/`). When the merchant opens your
app, the dashboard address is
`https://app.tassyir.io/{locale}/dashboard/{businessId}/apps/{handle}/{path}`,
and your frame loads:

> `hosting.url` + `admin.page` + the app path (`{path}`) + the dashboard's own
> query string

So every path below `admin.page` is your page: serve the same document for
all of them and route on the client.

* Allow the dashboard to frame your page, and nothing else:
  `Content-Security-Policy: frame-ancestors https://app.tassyir.io`.
* The page counts as shown at its frame's `load`, or at its first App Bridge
  call. With neither within 15 seconds, the dashboard shows a "didn't load"
  state with **Try again**.
* **Tassyir vouches for nothing in your page's address.** Never read a
  business, a user or a store from it to decide what to show or allow.
  App Bridge's context is for display only. Who is looking is what a verified
  ID token says ([Tokens](/guides/tokens#who-is-looking-the-id-token)).
* The dashboard never gives your page a Tassyir credential: the ID token is
  the only one. Your frame's cookies are third-party cookies, which browsers
  often block: do not build a session on them.

## A page

```ts browser theme={null}
import { createAppBridge, isAppBridgeError } from '@tassyir/app-bridge';

// Create it once, as early as the page loads: its first message tells the
// dashboard the page is up.
const bridge = createAppBridge();

// Each request to your server carries a NEW ID token: never keep one.
async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  const { token } = await bridge.idToken();
  const headers = new Headers(init.headers);
  headers.set('Authorization', `Bearer ${token}`);
  const response = await fetch(path, { ...init, headers });
  if (!response.ok) throw new Error(`${path} answered ${response.status}`);
  return (await response.json()) as T;
}

// The frame cannot see the dashboard's language, direction or theme.
bridge.on('context.changed', ({ locale, dir, theme }) => {
  document.documentElement.lang = locale;
  document.documentElement.dir = dir;
  document.documentElement.dataset['theme'] = theme;
});

await bridge.titleBar.set({ title: 'Reviews' });
const reviews =
  await api<{ id: string; orderNumber: string }[]>('/api/reviews');
document.querySelector('#count')!.textContent = String(reviews.length);

document.querySelector('#pick')!.addEventListener('click', async () => {
  try {
    const { selection } = await bridge.resource.pick({
      type: 'product',
      multiple: true,
    });
    if (selection.length === 0) return; // the merchant cancelled
    await api('/api/featured', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(selection.map((product) => product.id)),
    });
    await bridge.toast.show({
      message: `${selection.length} products featured`,
      tone: 'success',
    });
  } catch (error) {
    if (!isAppBridgeError(error)) throw error;
    // error.code is stable; error.fix says what to do about it.
    await bridge.toast.show({ message: error.message, tone: 'error' });
  }
});
```

Your server verifies each token with `tassyir.authenticate(idToken)` before
it answers ([Tokens](/guides/tokens#embedded-apps-one-offline-token-per-installation)).

## Calls

Every call posts one message to the dashboard and resolves with its answer,
or rejects with an `AppBridgeError`. The SDK checks each payload before
posting, so most mistakes are refused without a round trip.

| Call | Does |
| - | - |
| `idToken()` | A new 60-second ID token for this installation and the person looking. Never cached. |
| `toast.show({ message, tone? })` | A toast signed with your app's name. `tone`: `info` (default), `success`, `error`. |
| `modal.open({ path, title?, size? })` | One of your pages in a dashboard modal; resolves `{ closedBy: 'app' \| 'merchant' }` when it closes. |
| `modal.close()` | Closes the modal, from the page or from the modal itself. |
| `navigate({ path, replace? })` | Says your app moved to another of its pages; the dashboard's address follows. |
| `navigate({ dashboard, id? })` | Leaves your app for a dashboard page. |
| `saveBar.show({ saving? })` | Shows the dashboard's save bar, busy while `saving` is true. |
| `saveBar.hide()` | Hides it. |
| `titleBar.set({ title })` | Your page's title beside your app's name; `null` or `""` clears it. |
| `resource.pick({ type, multiple? })` | The dashboard's picker for products, collections or customers. |
| `context.get()` | The context: locale, direction, theme, current store. |

* **Text** (toasts, modal and page titles) is shown as text: control and
  bidi characters become spaces, white space is folded, and it is cut (150
  characters for a toast, 80 for a title). More than 2,000 characters is
  refused.
* **App paths** (`navigate`, `modal.open`) are relative to `admin.page` and
  start with one `/`, with an optional query: `/reviews/2?tab=sent`. No scheme
  or host, backslash, white space, control or bidi character, fragment, or
  `.`, `..` or empty segment. At most 1,024 characters before the `?` and
  2,048 in all.
* **`navigate({ path })`** does not reload your frame: show the page yourself
  (with your router), and the dashboard's address follows, as a new history
  entry or, with `replace: true`, in place. Back and Forward reload your frame
  at the address they land on.
* **`navigate({ dashboard })`** opens `home`, `orders`, `order` (with `id`),
  `customers`, `customer` (with `id`), `tracking`, `inventory`, `products`
  (the current store's) or `apps`.
* **A modal's page** may call only `idToken`, `toast.show`, `modal.close`,
  `resource.pick` and `context.get`. One modal and one picker at a time.
* `modal.open` and `resource.pick` wait for the merchant as long as the
  dialog is open. Every other call times out after 10 seconds, and every call
  takes an `AbortSignal`.

## The save bar

Show the dashboard's save bar while your page has unsaved changes. Its buttons
send events to your page:

```ts browser theme={null}
import { createAppBridge } from '@tassyir/app-bridge';

const bridge = createAppBridge();
let draft = { highlightFrom: '5000.00' };

document.querySelector('form')!.addEventListener('input', () => {
  void bridge.saveBar.show();
});

bridge.on('saveBar.save', async () => {
  await bridge.saveBar.show({ saving: true });
  const { token } = await bridge.idToken();
  const response = await fetch('/api/settings', {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(draft),
  });
  if (!response.ok) {
    // Keep the draft and the bar, so the merchant can save again.
    await bridge.saveBar.show({ saving: false });
    await bridge.toast.show({ message: 'Not saved, try again', tone: 'error' });
    return;
  }
  await bridge.saveBar.hide();
  await bridge.toast.show({ message: 'Saved', tone: 'success' });
});

bridge.on('saveBar.discard', async () => {
  draft = { highlightFrom: '5000.00' };
  await bridge.saveBar.hide();
});
```

The bar does not stop the merchant from leaving the page. When the page goes
away, the SDK hides the bar and clears the title, so neither outlives it.

## Pickers

`resource.pick` resolves when the merchant closes the dashboard's picker:
`selection` is empty when they cancelled, holds one item unless `multiple` is
true, and at most 50.

| `type` | Each item | Your installation needs |
| - | - | - |
| `product` | `{ id, name, image }` (`image` an https URL or `null`) | `read_products` |
| `collection` | `{ id, name }`, from the current store | `read_products` |
| `customer` | `{ id, provinceCode }`, plus `name` and `phone` with `read_customer_contact` | `read_customers` |

The person looking must also be allowed to read what the picker shows. An
installation limited to selected stores picks from the current store only,
which must be one of its stores.

## Context

```ts browser theme={null}
const stop = bridge.on('context.changed', ({ locale, dir, theme, storeId }) => {
  console.log(locale, dir, theme, storeId);
});
console.log(bridge.context.current); // null until the dashboard has sent it
stop();
```

The context is `{ locale: 'ar' | 'en', dir: 'rtl' | 'ltr', theme: 'light' |
'dark', storeId }`. `storeId` is the dashboard's current store, or `null`
when there is none or your installation is limited to other stores. Follow
`locale`, `dir` and `theme` so your page reads like the dashboard: Arabic
pages run right to left. The context is for display; it proves nothing.

## Errors

An `AppBridgeError` has a stable `code`, the `call` that failed, a `source`
(`dashboard` or `sdk`), a `message` for people and a `fix`.
`isAppBridgeError(error, code?)` narrows an unknown error.

| Code | Meaning |
| - | - |
| `INVALID_PAYLOAD` | The payload breaks the call's rules. |
| `RATE_LIMITED` | Over the call's limit for the minute. |
| `ID_TOKEN_UNAVAILABLE` | Tassyir cannot sign ID tokens right now; the dashboard tells the merchant. |
| `APP_UNAVAILABLE` | The installation cannot be opened any more (uninstalled, suspended, or no page). |
| `PERMISSION_DENIED` | The person looking may not do this. |
| `SCOPE_REQUIRED` | Your installation lacks the scope a pick needs. |
| `STORE_NOT_ALLOWED` | Your installation is limited to other stores than the current one. |
| `NO_STORE` | A collection pick with no current store. |
| `BUSY` | A modal or a picker is already open. |
| `NO_MODAL` | `modal.close` with no modal open. |
| `NOT_ALLOWED_HERE` | A call a modal's page may not make. |
| `INVALID_DESTINATION` | A place the dashboard cannot open now. |
| `FAILED` | Anything else; try again. |
| `NOT_EMBEDDED` | The page is not inside the dashboard's frame (`source: 'sdk'`). |
| `TIMEOUT` | No answer in time (`source: 'sdk'`). |

The [`@tassyir/app-bridge` README](https://github.com/tassyir/apps-sdk/tree/main/packages/app-bridge#errors)
lists the SDK's other codes.

## Limits

The dashboard counts calls per installation over a sliding minute, and
answers `RATE_LIMITED` past a call's limit. Past 240 messages a minute in all,
it drops messages without answering. The SDK counts what your page sends and
refuses first, so your page sees `RATE_LIMITED` rather than a timeout.

| Call | Per minute |
| - | - |
| `idToken` | 30 |
| `toast.show` | 20 |
| `modal.open` | 10 |
| `modal.close` | 30 |
| `navigate` | 30 |
| `saveBar.show` | 60 |
| `saveBar.hide` | 60 |
| `titleBar.set` | 60 |
| `resource.pick` | 10 |
| `context.get` | 60 |

A reloaded frame does not reset them: they last as long as the dashboard tab.


# Errors
Source: https://developers.tassyir.io/guides/errors

Every error code the Admin API and the token endpoint answer, and what to do about the common ones.

Every refusal says what failed and how to fix it. Act on the stable `code`,
show or log the `fix`, and quote the `requestId` when you ask Tassyir for
help.

## The shape

The Admin API answers errors as `application/problem+json`:

```json theme={null}
{
  "type": "https://developers.tassyir.io/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "You do not have permission: orders:read",
  "code": "PERMISSION_DENIED",
  "permission": "orders:read",
  "fix": "Request the read_orders scope in the app's manifest; it applies once the merchant consents to the new version.",
  "requestId": "a1b2c3"
}
```

| Member | Meaning |
| - | - |
| `code` | Stable and machine-readable. Act on it, never on `title` or `detail`. |
| `fix` | One sentence saying what to do, when there is one. |
| `status` | The HTTP status, also the answer's. |
| `requestId` | Names the request (also the `X-Request-Id` header). |
| `type` | `https://developers.tassyir.io/errors/<code in kebab case>`: an identifier. |
| others | What was refused: `permission`, `storeId`, `limit`, `retryAfter`, `errors`, `allowedFields`, … |

A 5xx never carries an internal message. The token endpoint is the one
exception to this shape: it answers OAuth errors ([below](#token-endpoint-errors)).

In `@tassyir/app`, an Admin API error is a `TassyirApiError` (`code`, `fix`,
`status`, `requestId`, `retryAfterSeconds`, `problem`), a token endpoint
error a `TassyirOAuthError` (its `code` is `OAUTH_` and the OAuth error in
capitals), and every other refusal a `TassyirError` with a `code` and a
`fix`. App Bridge's errors are listed in
[Embedded pages](/guides/embedded-pages#errors), the manifest's in
[The manifest](/guides/manifest#validate-before-you-upload), and those of the
hosted helpers (`HOSTED_PROPS_MISSING`, and `KEYS_UNAVAILABLE`,
`KEYS_NOT_CONFIGURED` and `WEBHOOK_NOT_A_DELIVERY` from
`verifyHostedWebhook`) in [Tassyir Hosting](/guides/tassyir-hosting#webhooks).

## Common errors and what to do

### `VALIDATION_FAILED`

HTTP 400. A parameter or a field failed validation, or is not one the route
takes. `errors` lists each problem. Fix the request: unknown parameters are
refused on purpose, so a misspelt filter never silently returns everything.

### `INVALID_CURSOR`

HTTP 400. The `cursor` is not this list's, was edited, or was made with other
filters. Send `nextCursor` back unchanged, with the same filters; to change a
filter, start again without a cursor.

### `INVALID_FIELDS`

HTTP 400. `fields` names a field the resource does not have. `allowedFields`
lists the valid names; fields are top-level only.

### `APP_TOKEN_REQUIRED`

HTTP 401. No `Authorization: Bearer` header. Send the installation's access token.

### `APP_TOKEN_INVALID`

HTTP 401. The token is unknown, expired or revoked, or its installation or app is
no longer active. Refresh it once (the SDK does). If the refresh is refused,
the installation was uninstalled, suspended or had its scopes changed: an
embedded app gets a new token on the next page view, a headless app needs a
new install code.

### `HOSTED_CALL_REFUSED`

HTTP 401. A hosted app's call through `ctx.props.TASSYIR` was refused: its
installation is uninstalled or suspended, or no longer runs a released
version. It is also the answer during an `app/uninstalled` or
`business/redact` delivery. Make the call from the request that received
`ctx.props.TASSYIR`; if the installation is active, retry after a short wait
([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)).

### `PERMISSION_DENIED`

HTTP 403. Your installation lacks the permission the route checks (`permission`).
The `fix` names the scope: add it to the manifest, upload a version, and the
merchant must accept the update. With an online token, the person may lack
it even when your app has it.

### `STORE_SCOPE_FORBIDDEN`

HTTP 460. Your request named a store (`storeId`) outside the stores the
merchant gave your installation. Use one of its stores; list them with
`GET /stores` (`read_stores`).

### `NOT_FOUND`

HTTP 404. No such route, or no resource your token can read under that id: a
resource of another store or business, or a malformed id, reads the same.

### `RATE_LIMITED`

HTTP 429. Your installation's bucket is empty. Wait `Retry-After` seconds, then
retry; spread your calls using the `RateLimit-*` headers.

### `BUSINESS_RATE_LIMITED`

HTTP 429. All the apps of this business together are past its ceiling. Wait
`Retry-After` seconds; other apps are using the room, so slow down.

### `API_BUSY`

HTTP 503. The API was too busy to take your call and did **nothing**. Wait
`Retry-After` (1 second) and send the same call again, a write included.

### `IDEMPOTENCY_KEY_REUSED`

HTTP 422. You reused an `Idempotency-Key` with another method, path, query or
body. Use a new key for a different write.

### `IDEMPOTENCY_KEY_IN_USE`

HTTP 409. A request with the same key is still running. Wait, then retry with the
same key: you will get its answer.

### `IDEMPOTENCY_UNAVAILABLE`

HTTP 503. Tassyir cannot check idempotency keys right now, so the write was not
attempted. Retry after `Retry-After` with the same key.

### `PLAN_FEATURE_REQUIRED`

HTTP 403. The merchant's plan lacks the feature (`feature`), such as stock at a
chosen location. Do without it, or tell the merchant.

### `SUBSCRIPTION_REQUIRED`

HTTP 422. The route needs a plan, and the business has no usable subscription.
Tell the merchant.

### `ORDER_LIMIT_REACHED`

HTTP 403. The order is waiting: it is past the plan's order allowance, and
cannot be confirmed until it unlocks (`orders/updated` with `waiting`).

### `ORDER_NOT_EDITABLE`

HTTP 409. The order is dispatched, delivered or returned (`orderStatus`): it can
no longer be edited, confirmed or cancelled.

### `ORDER_STATUS_CONFLICT`

HTTP 409. The order's status does not allow this move (`orderStatus`,
`requestedStatus`): read the order again and decide.

### `OFFER_NOT_OWNED`

HTTP 403. You tried to change, or read the codes or redemptions of, an offer
your installation did not create: the merchant's own, or another app's. An
app writes only its own offers. Create your own offer with `POST /offers` and
change that one ([Write offers and codes](/guides/write-offers#you-write-only-the-offers-you-own)).
The merchant's dashboard has a counterpart you never get: editing or
duplicating an **app-owned** offer there answers 409 `OFFER_APP_OWNED`,
because such an offer is changed in the app that owns it.

### `MEDIA_URL_NOT_ALLOWED`

HTTP 400. An image is not on `https://cdn.tassyir.io/` and not already on the
resource (`field`, `url`). Upload it with `POST /images` first
([Products and collections](/guides/products-and-collections#bring-an-image-onto-the-cdn)).

### `APP_DATA_KEY_NOT_DECLARED`

HTTP 400. Your installation's version does not declare that key for that owner
type. Declare it under `[[data.definitions]]`, upload, and have the merchant
accept the update.

### `INTERNAL_ERROR`

HTTP 500. Tassyir's fault. Retry reads with backoff; retry writes only with the
same `Idempotency-Key`. Quote the `requestId` if it persists.

### `SERVICE_UNAVAILABLE`

HTTP 503. Something Tassyir depends on is down. Retry with backoff, writes with the
same `Idempotency-Key`.

## Hosted apps: the binding's own codes

A hosted app calls the Admin API through `ctx.props.TASSYIR.fetch`
([Tassyir Hosting](/guides/tassyir-hosting#call-the-admin-api)). The binding checks
each call before it sends it and answers some refusals itself, in the same
problem shape but without a `requestId`: they never reached the API.
`@tassyir/app` lists all nine in `HOSTED_BINDING_ERRORS`, and `hostedAdmin`
throws them as `TassyirApiError`s. Six of them are the API's own codes
(`METHOD_NOT_ALLOWED`, `BAD_REQUEST`, `IDEMPOTENCY_KEY_INVALID`,
`PAYLOAD_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, and `SERVICE_UNAVAILABLE` when
the API did not answer within 30 seconds). Three exist only there, so the
API's reference does not list them:

### `HOSTED_PATH_NOT_ALLOWED`

HTTP 400. The call was not to an Admin API path. Call `/apps/<version>/…`
with segments of letters, digits, `_` and `-` only: no other path, no `//`,
no trailing `/`, no percent-encoding and no `;`. The binding also reads
Tassyir's two public key documents, with `GET` at exactly
`/apps/webhook-keys` and `/apps/.well-known/jwks.json` (another method there
is `METHOD_NOT_ALLOWED`).

### `RESPONSE_TOO_LARGE`

HTTP 502. The API's answer was larger than a hosted app may receive (8 MiB).
Ask for less: a smaller `limit`, or `?fields=` with only the fields you read.

### `TASSYIR_BINDING_NOT_AVAILABLE`

HTTP 503. Calls to the Admin API from a hosted app are not available right
now; nothing was sent. Try again later.

## Every Admin API code

Generated from the OpenAPI document of API version `2026-10` that `@tassyir/app` is typed from (55 operations under `/apps/2026-10/`). An operation lists every code it can answer, per status, in that document; a status fallback (the code of a refusal that carries no more specific one) is in its error catalogue and may come from any operation.

| Code | HTTP | Answered by |
| - | - | - |
| [`API_BUSY`](/errors/api-busy) | 503 | every operation |
| [`APP_DATA_KEY_NOT_DECLARED`](/errors/app-data-key-not-declared) | 400 | `PUT /data/{ownerType}/{ownerId}/{key}` |
| [`APP_DATA_LIMIT_REACHED`](/errors/app-data-limit-reached) | 409 | `PUT /data/{ownerType}/{ownerId}/{key}` |
| [`APP_DATA_VALUE_INVALID`](/errors/app-data-value-invalid) | 400 | `PUT /data/{ownerType}/{ownerId}/{key}` |
| [`APP_DATA_VALUE_TOO_LARGE`](/errors/app-data-value-too-large) | 400 | `PUT /data/{ownerType}/{ownerId}/{key}` |
| [`APP_TOKEN_INVALID`](/errors/app-token-invalid) | 401 | every operation |
| [`APP_TOKEN_REQUIRED`](/errors/app-token-required) | 401 | every operation |
| [`BAD_REQUEST`](/errors/bad-request) | 400 | 23 operations |
| [`BRAND_NOT_FOUND`](/errors/brand-not-found) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`BULK_EXPORTS_NOT_CONFIGURED`](/errors/bulk-exports-not-configured) | 503 | `POST /bulk/exports` |
| [`BULK_EXPORT_IN_PROGRESS`](/errors/bulk-export-in-progress) | 409 | `POST /bulk/exports` |
| [`BULK_EXPORT_RATE_LIMITED`](/errors/bulk-export-rate-limited) | 429 | `POST /bulk/exports` |
| [`BUSINESS_RATE_LIMITED`](/errors/business-rate-limited) | 429 | every operation |
| [`CANCEL_NOTE_REQUIRED`](/errors/cancel-note-required) | 400 | `POST /orders/{id}/cancel` |
| [`CANCEL_REASON_INVALID`](/errors/cancel-reason-invalid) | 400 | `POST /orders/{id}/cancel` |
| [`COLLECTION_CONDITIONAL_LIMIT`](/errors/collection-conditional-limit) | 409 | `PATCH /collections/{id}`, `POST /collections` |
| [`COLLECTION_DEPTH_LIMIT`](/errors/collection-depth-limit) | 409 | `PATCH /collections/{id}`, `POST /collections` |
| [`COLLECTION_NOT_FOUND`](/errors/collection-not-found) | 400 | `POST /products` |
| [`COLLECTION_PARENT_CYCLE`](/errors/collection-parent-cycle) | 409 | `PATCH /collections/{id}` |
| [`COLLECTION_PARENT_NOT_FOUND`](/errors/collection-parent-not-found) | 404 | `PATCH /collections/{id}`, `POST /collections` |
| [`COLLECTION_PRODUCT_WRONG_STORE`](/errors/collection-product-wrong-store) | 400 | `PATCH /collections/{id}/products` |
| [`COLLECTION_RULE_INVALID`](/errors/collection-rule-invalid) | 400 | `PATCH /collections/{id}`, `POST /collections` |
| [`CONFLICT`](/errors/conflict) | 409 | any operation, as a fallback |
| [`DELIVERY_SPEED_UNAVAILABLE`](/errors/delivery-speed-unavailable) | 400 | `PATCH /orders/{id}`, `POST /orders` |
| [`DELIVERY_SPEED_UNSUPPORTED`](/errors/delivery-speed-unsupported) | 400 | `PATCH /orders/{id}` |
| [`DEV_STORE_ORDER_LIMIT_REACHED`](/errors/dev-store-order-limit-reached) | 429 | `POST /orders` |
| [`FORBIDDEN`](/errors/forbidden) | 403 | `GET /inventory-levels`, `GET /inventory-levels/{id}`, `POST /inventory-levels/{id}/adjust`, `POST /orders` |
| [`HOSTED_CALL_REFUSED`](/errors/hosted-call-refused) | 401 | every operation |
| [`HTML_NOT_ALLOWED`](/errors/html-not-allowed) | 400 | `PATCH /collections/{id}`, `PATCH /products/{id}`, `POST /collections`, `POST /products` |
| [`IDEMPOTENCY_KEY_INVALID`](/errors/idempotency-key-invalid) | 400 | 28 operations |
| [`IDEMPOTENCY_KEY_IN_USE`](/errors/idempotency-key-in-use) | 409 | 28 operations |
| [`IDEMPOTENCY_KEY_REUSED`](/errors/idempotency-key-reused) | 422 | 28 operations |
| [`IDEMPOTENCY_UNAVAILABLE`](/errors/idempotency-unavailable) | 503 | 28 operations |
| [`IMAGE_FETCH_FAILED`](/errors/image-fetch-failed) | 400 | `POST /images` |
| [`IMAGE_QUOTA_REACHED`](/errors/image-quota-reached) | 429 | `POST /images` |
| [`IMAGE_TOO_LARGE`](/errors/image-too-large) | 400 | `POST /images` |
| [`IMAGE_TYPE_NOT_ALLOWED`](/errors/image-type-not-allowed) | 400 | `POST /images` |
| [`IMAGE_URL_NOT_ALLOWED`](/errors/image-url-not-allowed) | 400 | `POST /images` |
| [`INSUFFICIENT_AT_LOCATION`](/errors/insufficient-at-location) | 409 | `POST /inventory-levels/{id}/adjust` |
| [`INTERNAL_ERROR`](/errors/internal-error) | 500 | every operation |
| [`INVALID_CURSOR`](/errors/invalid-cursor) | 400 | 13 operations |
| [`INVALID_FIELDS`](/errors/invalid-fields) | 400 | 49 operations |
| [`LOCATION_NOT_FOUND`](/errors/location-not-found) | 400, 404 | `POST /inventory-levels/{id}/adjust` |
| [`MEDIA_URL_NOT_ALLOWED`](/errors/media-url-not-allowed) | 400 | `PATCH /collections/{id}`, `PATCH /products/{id}`, `PATCH /products/{id}/variants/{variantId}`, `POST /collections`, `POST /products` |
| [`METHOD_NOT_ALLOWED`](/errors/method-not-allowed) | 405 | any operation, as a fallback |
| [`NOT_FOUND`](/errors/not-found) | 404 | 40 operations |
| [`OFFER_ARCHIVED`](/errors/offer-archived) | 409 | `PATCH /offers/{id}`, `POST /offers/{id}/codes`, `POST /offers/{id}/codes/bulk`, `POST /offers/{id}/pause`, `POST /offers/{id}/publish`, `POST /offers/{id}/resume` |
| [`OFFER_CODE_INVALID`](/errors/offer-code-invalid) | 400 | `POST /offers/{id}/codes` |
| [`OFFER_CODE_NOT_FOUND`](/errors/offer-code-not-found) | 404 | `POST /offers/{id}/codes/{codeId}/disable`, `POST /offers/{id}/codes/{codeId}/enable` |
| [`OFFER_CODE_TAKEN`](/errors/offer-code-taken) | 409 | `POST /offers`, `POST /offers/{id}/codes` |
| [`OFFER_ENDED`](/errors/offer-ended) | 409 | `POST /offers/{id}/pause`, `POST /offers/{id}/resume` |
| [`OFFER_GONE`](/errors/offer-gone) | 409 | `POST /orders` |
| [`OFFER_INVALID`](/errors/offer-invalid) | 400 | `PATCH /offers/{id}`, `POST /offers`, `POST /offers/{id}/publish` |
| [`OFFER_KIND_IMMUTABLE`](/errors/offer-kind-immutable) | 400 | `PATCH /offers/{id}` |
| [`OFFER_KIND_NOT_AVAILABLE`](/errors/offer-kind-not-available) | 400 | `POST /offers` |
| [`OFFER_LIMIT_REACHED`](/errors/offer-limit-reached) | 409 | `POST /orders` |
| [`OFFER_NOT_CODE_METHOD`](/errors/offer-not-code-method) | 409 | `POST /offers/{id}/codes`, `POST /offers/{id}/codes/bulk` |
| [`OFFER_NOT_FOUND`](/errors/offer-not-found) | 404 | 9 operations |
| [`OFFER_NOT_OWNED`](/errors/offer-not-owned) | 403 | 11 operations |
| [`OFFER_NOT_PUBLISHED`](/errors/offer-not-published) | 409 | `POST /offers/{id}/pause`, `POST /offers/{id}/resume` |
| [`OFFER_STORE_NOT_FOUND`](/errors/offer-store-not-found) | 404 | `POST /offers` |
| [`OFFER_TARGET_NOT_FOUND`](/errors/offer-target-not-found) | 400 | `PATCH /offers/{id}`, `POST /offers` |
| [`OFFER_TARGET_OUTSIDE_STORE`](/errors/offer-target-outside-store) | 400 | `PATCH /offers/{id}`, `POST /offers` |
| [`OFFER_VERSION_CONFLICT`](/errors/offer-version-conflict) | 409 | `PATCH /offers/{id}`, `POST /offers/{id}/pause`, `POST /offers/{id}/publish`, `POST /offers/{id}/resume` |
| [`ORDER_DUPLICATE`](/errors/order-duplicate) | 409 | `POST /orders` |
| [`ORDER_LIMIT_REACHED`](/errors/order-limit-reached) | 403 | `POST /orders/{id}/confirm` |
| [`ORDER_NOT_EDITABLE`](/errors/order-not-editable) | 409 | `PATCH /orders/{id}`, `POST /orders/{id}/cancel`, `POST /orders/{id}/confirm`, `POST /orders/{id}/schedule` |
| [`ORDER_PRICING_LOCKED`](/errors/order-pricing-locked) | 400 | `PATCH /orders/{id}` |
| [`ORDER_STATUS_CONFLICT`](/errors/order-status-conflict) | 409 | `POST /orders/{id}/cancel`, `POST /orders/{id}/confirm`, `POST /orders/{id}/schedule` |
| [`PAYLOAD_TOO_LARGE`](/errors/payload-too-large) | 413 | 22 operations |
| [`PERMISSION_DENIED`](/errors/permission-denied) | 403 | 54 operations |
| [`PLAN_FEATURE_REQUIRED`](/errors/plan-feature-required) | 403 | `GET /inventory-levels`, `GET /inventory-levels/{id}`, `POST /inventory-levels/{id}/adjust` |
| [`PLAN_LIMIT_REACHED`](/errors/plan-limit-reached) | 403 | `PATCH /offers/{id}`, `POST /offers/{id}/publish`, `POST /offers/{id}/resume` |
| [`PRODUCT_DEFAULT_VARIANT`](/errors/product-default-variant) | 409 | `PATCH /products/{id}/variants/{variantId}` |
| [`PRODUCT_OPTIONS_REQUIRE_VARIANTS`](/errors/product-options-require-variants) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_OPTION_DUPLICATE_NAME`](/errors/product-option-duplicate-name) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_OPTION_DUPLICATE_VALUE`](/errors/product-option-duplicate-value) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_OPTION_NOT_FOUND`](/errors/product-option-not-found) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_OPTION_NO_VALUES`](/errors/product-option-no-values) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_OPTION_VALUE_EMPTY`](/errors/product-option-value-empty) | 400 | `PATCH /products/{id}` |
| [`PRODUCT_OPTION_VALUE_NOT_FOUND`](/errors/product-option-value-not-found) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_SLUG_INVALID`](/errors/product-slug-invalid) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_SLUG_TAKEN`](/errors/product-slug-taken) | 409 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_COMBINATION_MISMATCH`](/errors/product-variant-combination-mismatch) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_COUNT_MISMATCH`](/errors/product-variant-count-mismatch) | 400 | `PATCH /products/{id}`, `PATCH /products/{id}/variants/{variantId}`, `POST /products` |
| [`PRODUCT_VARIANT_DUPLICATE_COMBINATION`](/errors/product-variant-duplicate-combination) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_DUPLICATE_OPTION`](/errors/product-variant-duplicate-option) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_INVALID_VALUE`](/errors/product-variant-invalid-value) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_MISSING_COMBINATIONS`](/errors/product-variant-missing-combinations) | 400 | `PATCH /products/{id}`, `PATCH /products/{id}/variants/{variantId}`, `POST /products` |
| [`PRODUCT_VARIANT_MISSING_OPTION`](/errors/product-variant-missing-option) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_SELECTED_COUNT`](/errors/product-variant-selected-count) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_VARIANT_UNKNOWN_OPTION`](/errors/product-variant-unknown-option) | 400 | `PATCH /products/{id}`, `POST /products` |
| [`PRODUCT_WRITE_TIMEOUT`](/errors/product-write-timeout) | 400 | `PATCH /products/{id}`, `PATCH /products/{id}/variants/{variantId}`, `POST /products` |
| [`RATE_LIMITED`](/errors/rate-limited) | 429 | every operation |
| [`REQUEST_FAILED`](/errors/request-failed) | 4xx | any operation, as a fallback |
| [`SERVICE_UNAVAILABLE`](/errors/service-unavailable) | 503 | every operation |
| [`STORE_REQUIRED`](/errors/store-required) | 400 | `POST /orders` |
| [`STORE_SCOPE_FORBIDDEN`](/errors/store-scope-forbidden) | 460 | 17 operations |
| [`SUBSCRIPTION_REQUIRED`](/errors/subscription-required) | 422 | `GET /inventory-levels`, `GET /inventory-levels/{id}`, `POST /inventory-levels/{id}/adjust` |
| [`UNAUTHORIZED`](/errors/unauthorized) | 401 | any operation, as a fallback |
| [`UNPROCESSABLE_ENTITY`](/errors/unprocessable-entity) | 422 | any operation, as a fallback |
| [`UNSUPPORTED_MEDIA_TYPE`](/errors/unsupported-media-type) | 415 | 22 operations |
| [`VALIDATION_FAILED`](/errors/validation-failed) | 400 | 53 operations |

## Token endpoint errors

`POST /apps/oauth/token` answers OAuth errors, `{ "error": "…", "error_description": "…" }`, never problem+json.

| `error` | HTTP |
| - | - |
| `invalid_client` | 401 |
| `invalid_grant` | 400 |
| `invalid_request` | 400, 413 |
| `slow_down` | 429 |
| `temporarily_unavailable` | 503 |
| `unauthorized_client` | 400 |
| `unsupported_grant_type` | 400 |


# Getting started
Source: https://developers.tassyir.io/guides/getting-started

Create an app with npm create tassyir-app, run it behind an https tunnel, and install it on a dev store.

You want an app running on your machine, installed on a test business, with
its page open in the Tassyir dashboard. This guide gets you there in about
fifteen minutes. The app you start from shows a business's pending orders,
keeps one setting in Tassyir, and logs the webhooks it receives.

## What you need

* **Node 22.18 or later.** The starter runs its TypeScript directly on Node.
* **A Tassyir account** at [app.tassyir.io](https://app.tassyir.io).
* **A tunnel** that gives your machine a public **https** address on port
  443, such as
  [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
  or [ngrok](https://ngrok.com). Tassyir only calls https addresses on port
  443 with a public hostname: never `localhost`, an IP address or another
  port.

A command-line tool, `tassyir`, is coming to do the console steps below from
a terminal. Until it ships, this guide uses the developer console in the
dashboard.

## 1. Create the project

```bash theme={null}
npm create tassyir-app@latest review-requests
```

It writes `review-requests/` and prints the next steps. The handle (the
folder's name by default) is your app's permanent, unique name on Tassyir: it
becomes the `handle` in `tassyir.app.toml`. Pass options after `--`:

```bash theme={null}
npm create tassyir-app@latest review-requests -- --name "Review Requests" --json
```

The project is ready for coding agents: it has an `AGENTS.md`, a `CLAUDE.md`
and a Claude Code skill that explains the Tassyir contract.

Then install and set up:

```bash theme={null}
cd review-requests
npm install
npm run setup
```

`npm run setup` writes `.env` from `.env.example`, with a new random key that
encrypts the tokens the app stores.

## 2. Give your server a public address

Start the tunnel to port 3000 and leave it running:

```bash theme={null}
cloudflared tunnel --url http://localhost:3000
```

Copy the https address it prints into `hosting.url` in `tassyir.app.toml`
(no trailing `/`), then check the manifest with the Tassyir API's own
validator:

```bash theme={null}
npm run validate
```

A quick tunnel's address changes every time it starts, and every change is a
new version of your manifest that the dev store must accept again. A tunnel
that keeps its hostname (a named tunnel on your own domain, a reserved ngrok
domain) saves that.

## 3. Create the app in the developer console

1. Open [app.tassyir.io/en/developers](https://app.tassyir.io/en/developers)
   and turn on developer mode. It is free, on every plan.
2. **Create an app** and choose "Your own server". Its handle must be exactly
   the `handle` of `tassyir.app.toml`. It never changes afterwards.
3. In the app's **Credentials** tab, create a client secret. It is shown
   once: copy it now.
4. Fill in `.env`:
   * `TASSYIR_CLIENT_ID`: the client id (`app_…`), on the Credentials tab;
   * `TASSYIR_CLIENT_SECRET`: the secret (`tsy_cs_…`);
   * `TASSYIR_APP_ID`: the app's numeric id, the number at the end of the
     app's address in the console (`/developers/apps/<id>`). Webhooks name
     your app by this id; it is not the client id.
5. In the **Versions** tab, upload `tassyir.app.toml`. Your first version is
   current at once: custom apps are not reviewed.

Never commit `.env`, and never put the secret in your page or a URL.

## 4. Create a dev store

In the console, open **Dev stores** and create one. A dev store is a business
for testing: about 30 products, 200 orders in every state across the 58
wilayas, and buyers with fake phone numbers. It costs nothing, and nothing it
does reaches the outside world: carriers, ad pixels, WhatsApp and payments
are switched off, and its storefront takes no orders. See
[Dev stores](/guides/dev-stores).

## 5. Start the server

```bash theme={null}
npm run dev
```

It listens on `http://localhost:3000`, restarts when `src/` changes, and
rebuilds the page. If a setting is missing, it names it and says where to
find it.

## 6. Install the app

On the app's **Overview** tab in the console, copy the install link, open it,
pick your dev store, and install. The install screen lists the scopes your
manifest asks for, with your reason for each ([Scopes and
consent](/guides/scopes-and-consent)).

The dashboard then opens your page: the dev store's pending orders, and a
setting saved in Tassyir through the dashboard's save bar. Your page asked App
Bridge for an ID token, your server verified it and exchanged it for an
access token, then called the Admin API ([Tokens](/guides/tokens)).

## 7. Watch webhooks

Create an order in the dev store's dashboard: your server logs
`orders/created`. In the console, the **Installs** tab sends a test delivery
to your endpoint, and the **Webhook deliveries** tab shows every attempt and
replays one ([Webhooks](/guides/webhooks)).

## Changing the manifest

Whenever you change `tassyir.app.toml` (a scope, a webhook topic, the
address):

1. `npm run validate`;
2. upload it in the **Versions** tab as a new version;
3. accept the update on the dev store: **Apps**, **Installed apps**,
   **Update**.

An installation stays on the version it accepted until someone accepts the
new one, and a version that adds a scope or a new address asks for consent
again. See [Scopes and consent](/guides/scopes-and-consent#new-versions-and-updates).

## Deploying

Any host that runs Node 22.18 or later behind https on port 443 works:

1. on the host, `npm ci`, `npm run build`, then `npm start`, with the
   variables of `.env` set in the host's environment (never upload `.env`);
2. set `hosting.url` to the host's address, upload the manifest, and accept
   the update.

The starter keeps its tokens in one file on disk, so run one process with a
persistent disk. To run several, move the tokens to a shared database and
add a refresh lock ([Tokens](/guides/tokens#refresh-safely)).

## When something fails

| You see | Do |
| - | - |
| The page says "Open this page from the Tassyir dashboard" | It runs outside the dashboard's frame: open it from **Apps** in the dashboard. |
| The dashboard says the app did not load | Is the tunnel up, and is its address the manifest's `hosting.url`, uploaded and accepted? |
| `ID_TOKEN_UNAVAILABLE` in the browser console | Tassyir cannot sign ID tokens right now; nothing in your app can fix it. Try again later. |
| `invalid_client` from the token endpoint | Check the client id and secret. A revoked secret, or one rotated more than 24 hours ago, is refused. |
| 403 `PERMISSION_DENIED` | Add the scope its `fix` names to `[access]`, upload, and accept the update. |
| Webhooks refused with `WEBHOOK_WRONG_APP` | `TASSYIR_APP_ID` must be the numeric app id, not the client id. |
| Webhooks refused with `WEBHOOK_UNKNOWN_INSTALLATION` | Open the app's page once, or wait for `app/installed`: Tassyir delivers the refused event again. |

## Next

* [The manifest](/guides/manifest): every field of `tassyir.app.toml`.
* [Admin API conventions](/guides/admin-api): lists, errors, retries and rate
  limits, before you call more of the API.
* [Webhooks](/guides/webhooks): the topics, and handling them safely.


# Build apps for Tassyir
Source: https://developers.tassyir.io/guides/index

What a Tassyir app is, the parts of the app contract, and where each guide fits.

[Tassyir](https://tassyir.io) is the back office of e-commerce merchants in
Algeria: orders (mostly cash on delivery), products and stock, delivery
carriers, customers, and several stores per business. An app adds to it. A
merchant installs your app on a business, and the app then reads and changes
that business's data, receives its events, and can show its own pages inside
the dashboard.

## What an app is

**An installed app is a team member of the business.** It acts with exactly
the scopes the merchant granted, only in the stores the merchant gave it, and
under the merchant's plan: a plan limit refuses an app the way it refuses the
merchant. The changes an app makes to orders, the catalogue and stock are
written to the business's activity log under the app's name.

An app runs on **your own server** today (`hosting.mode = "external"` in the
manifest). [Tassyir Hosting](/guides/tassyir-hosting), where an app runs on
Tassyir with no server to manage, opens later; an app moves there with the
same manifest, API and webhooks.

Apps are **custom apps** for now: one installs on the businesses its
developer owns, and on one other business the developer names. A public
catalogue of apps comes later.

## The parts

| Part | What it is | Guide |
| - | - | - |
| Manifest | `tassyir.app.toml`: what the app is, the scopes it asks for, its address, page and webhooks | [The manifest](/guides/manifest) |
| Scopes and consent | What a merchant grants on install, and how a new version asks again | [Scopes and consent](/guides/scopes-and-consent) |
| Tokens | ID tokens, offline and online access tokens, refresh tokens, install codes | [Tokens](/guides/tokens) |
| Embedded pages | Your page inside the dashboard, talking to it through App Bridge | [Embedded pages and App Bridge](/guides/embedded-pages) |
| Webhooks | Signed deliveries of the business's events | [Webhooks](/guides/webhooks) |
| Admin API | The versioned REST API an app calls | [Admin API conventions](/guides/admin-api) |
| Orders | Read, create, edit, confirm, cancel and comment on orders | [Orders](/guides/orders) |
| Products and collections | The catalogue, its images and collections | [Products and collections](/guides/products-and-collections) |
| Stock | Stock levels, and correcting a count | [Stock](/guides/stock) |
| Customers | Buyers and their delivery record, and the contact data scope | [Customers and contact data](/guides/customers) |
| Offers | The merchant's pricing offers, read-only, with their webhooks | [Offers](/guides/offers) |
| Write offers and codes | Run offers of your own: influencer codes in bulk, redemptions, app-owned offer types | [Write offers and codes](/guides/write-offers) |
| Stores and delivery | A business's stores, carriers and delivery prices | [Stores and delivery](/guides/stores-and-delivery) |
| App data | Values your app keeps in Tassyir, next to the merchant's resources | [App data](/guides/app-data) |
| Storefront blocks | Not live yet: HTML your app adds to store pages, a Liquid template Tassyir checks and renders | [Storefront blocks](/guides/storefront-blocks) |
| Dev stores | Test businesses with synthetic data, where nothing reaches the outside world | [Dev stores](/guides/dev-stores) |
| Tassyir Hosting | Running the app on Tassyir: deploying, the scan, what each request receives | [Tassyir Hosting](/guides/tassyir-hosting) |
| Compliance and uninstall | What happens when a merchant uninstalls, and the buyer data requests an app must honour | [Compliance and uninstall](/guides/compliance-and-uninstall) |
| Publishing | Listing the app in the marketplace: the listing, the terms, the review checks, ratings | [Publishing to the marketplace](/guides/publishing) |
| Errors | Every error code, and what to do about the common ones | [Errors](/guides/errors) |

Start with [Getting started](/guides/getting-started): it creates an app, runs it
on your machine and installs it on a dev store.

## The packages

| Package | Use it for |
| - | - |
| [`create-tassyir-app`](https://github.com/tassyir/apps-sdk/tree/main/packages/create-tassyir-app) | `npm create tassyir-app`: a working app to start from |
| [`@tassyir/app`](https://github.com/tassyir/apps-sdk/tree/main/packages/app) | Your server: tokens, ID-token and webhook verification, the typed Admin API client |
| [`@tassyir/app-bridge`](https://github.com/tassyir/apps-sdk/tree/main/packages/app-bridge) | Your page in the dashboard: ID tokens, toasts, modals, the save bar, navigation, pickers |
| [`@tassyir/app-manifest`](https://github.com/tassyir/apps-sdk/tree/main/packages/app-manifest) | Validating `tassyir.app.toml` with the same code the Tassyir API runs |
| [`tassyir`](https://github.com/tassyir/apps-sdk/tree/main/packages/cli) | The command line: sign in, create apps, validate and deploy, preview blocks, submit |
| [`@tassyir/storefront-blocks`](https://github.com/tassyir/apps-sdk/tree/main/packages/storefront-blocks) | Writing and testing storefront blocks with the code the Tassyir API runs (not live yet) |

## Addresses

| What | Where |
| - | - |
| Admin API | `https://api.tassyir.io/apps/2026-10/` |
| Token endpoint | `POST https://api.tassyir.io/apps/oauth/token` |
| ID-token public keys | `GET https://api.tassyir.io/apps/.well-known/jwks.json` |
| Webhook public keys | `GET https://api.tassyir.io/apps/webhook-keys` |
| Your page in the dashboard | `https://app.tassyir.io/{locale}/dashboard/{businessId}/apps/{handle}/{path}` |
| Developer console | `https://app.tassyir.io/en/developers` |

## Rules every app follows

* **The ID token is the only proof of who is looking.** Your page's address
  says nothing Tassyir vouches for. Verify an ID token on your server
  ([Tokens](/guides/tokens)).
* **Money is a decimal string** (`"2500.00"`) next to a `currency`. Never turn
  it into a JavaScript number ([Admin API conventions](/guides/admin-api)).
* **Act on an error's `code`, and read its `fix`.** Every refusal has a stable
  code and one sentence that says what to do ([Errors](/guides/errors)).
* **Webhooks arrive at least once, in any order.** Verify each one on its raw
  body, and skip a `webhook-id` you already handled ([Webhooks](/guides/webhooks)).
* **Ask for the fewest scopes.** A merchant sees every scope, and a new one
  needs their consent again ([Scopes and consent](/guides/scopes-and-consent)).
* **Never put a secret in a page, a URL, a log or a repository.** Client
  secrets and tokens live on your server.

## About the code in these guides

The code is TypeScript on the published packages, and a check compiles every
sample against them. Server code runs on Node 22.18 or later and on
Workers-like runtimes; page code runs in the browser. To keep samples short,
some use names set up once elsewhere:

| Name | What it is |
| - | - |
| `tassyir` | Your server's `TassyirApp`, from `createTassyirApp` ([Tokens](/guides/tokens)) |
| `admin` | An Admin API client for one installation, `tassyir.admin(installationId)` ([Admin API](/guides/admin-api)) |
| `installationId` | The installation your code is working for |
| `bridge` | Your page's App Bridge, from `createAppBridge()` ([Embedded pages](/guides/embedded-pages)) |

Every API version is dated. These guides describe version `2026-10`.


# The manifest
Source: https://developers.tassyir.io/guides/manifest

Describe your app in tassyir.app.toml, validate it with the API's own validator, and upload it as a version.

Your app is described by one file, `tassyir.app.toml`: its name and handle,
the scopes it asks for and why, where it runs, its page in the dashboard, the
webhooks it receives and the values it keeps in Tassyir. You upload the file
as a **version**; merchants consent to a version, and their installation
stays on it until they accept a newer one.

## An example

An app on your own server with a page in the dashboard:

```toml theme={null}
name        = "Review Requests"
handle      = "review-requests"
api_version = "2026-10"

[access]
scopes          = ["read_orders", "read_products"]
optional_scopes = ["read_customer_contact"]

[access.scope_reasons]
read_orders           = "Find delivered orders to ask for a review"
read_products         = "Show the product in the review request"
read_customer_contact = "Send the review request to the buyer's phone"

[hosting]
mode = "external"
url  = "https://reviews.example.com"

[admin]
page = "/"

[[webhooks]]
topics = ["orders/delivered", "app/uninstalled"]
uri    = "/webhooks"

[[webhooks]]
topics = ["customers/data_request", "customers/redact", "business/redact"]
uri    = "/webhooks/privacy"

[[data.definitions]]
owner      = "product"
key        = "rating"
type       = "json"
visibility = "app"
```

A headless app (no page) gets its first tokens from an install code sent to
its `auth.callback_url`, and may send a webhook to another host:

```toml theme={null}
name        = "Sheets Sync"
handle      = "sheets-sync"
api_version = "2026-10"

[access]
scopes        = ["write_orders", "read_products"]
scope_reasons = { write_orders = "Create orders from the rows of your sheet", read_products = "Match sheet rows to your products" }

[hosting]
mode = "external"
url  = "https://sync.example.com/tassyir"

[auth]
callback_url = "https://sync.example.com/tassyir/callback"

[[webhooks]]
topics = ["orders/created", "products/updated"]
uri    = "/hooks"

[[webhooks]]
topics = ["customers/data_request", "customers/redact", "business/redact"]
uri    = "https://privacy.example.com/tassyir"
```

## Fields

| Field | Rule |
| - | - |
| `name` | Required. 1 to 50 characters on one line: no control, line-break or invisible characters (bidi controls, zero-width), no spaces around it. Arabic and English listing names are set in the console. |
| `handle` | Required. 3 to 40 lowercase letters and digits, in runs joined by single hyphens. Unique on Tassyir, never changes, and must equal the handle of the app in the console. Some names are reserved (`www`, `api`, `tassyir`, …). |
| `api_version` | Required. `2026-10`. |
| `access.scopes` | The scopes the app needs ([Scopes and consent](/guides/scopes-and-consent)). Each once. |
| `access.optional_scopes` | Scopes the merchant may tick. Never also in `scopes`, and never one a required scope already implies. |
| `access.scope_reasons` | One sentence per requested scope, required and optional, shown on the install screen: 10 to 200 characters, the `name` text rules. No reason for a scope you do not request. |
| `hosting.mode` | Required. `external`: the app runs on your server. `tassyir`: the app runs on [Tassyir Hosting](/guides/tassyir-hosting), whose uploads are refused until it opens. |
| `hosting.url` | Required for `external`. `https://host` or `https://host/path`, at most 512 characters: no port (443 only), no user or password, no query, fragment or trailing `/`. The host is a public lowercase hostname: no IP address, no private name (`localhost`, `.local`, `.test`, …), nothing on Tassyir's domains. |
| `hosting.allowed_hosts` | Required for `tassyir` (an empty list when the code calls no other service), refused for `external`. At most 20 hosts the app's code calls, each once: a lowercase hostname of two labels or more, or `*.` + one for its subdomains. No scheme, port, path, IP address, private name or Tassyir domain: a hosted app calls Tassyir through `ctx.props.TASSYIR`. |
| `auth.callback_url` | Optional, `external` only. Where a headless app receives its install code ([Tokens](/guides/tokens#headless-apps-the-install-code)). The `hosting.url` rules, but a trailing `/` is allowed. |
| `admin.page` | Optional. Your page in the dashboard: a path on `hosting.url` (on a hosted app, its own address), starting with `/` (not `//`), at most 256 characters, no query, fragment, backslash, space, `.` / `..` / empty segment or encoded slash; on a hosted app, never `/.tassyir` or below. Omit it for a headless app. |
| `webhooks` | At most 10 entries, each `topics` (one or more) and `uri`. A topic is subscribed once in the whole manifest, and needs the scope that reads its resource ([Webhooks](/guides/webhooks#topics)). `uri` is a path on `hosting.url` (the `admin.page` rules), or for an external app an absolute https URL (the `hosting.url` rules). |
| `data.definitions` | At most 50 keys of [app data](/guides/app-data): `owner` (`business`, `store`, `product`, `order`, `customer`), `key` (`[a-z][a-z0-9_]{0,63}`, unique per owner), `type` (`string`, `number`, `integer`, `boolean`, `json`), `visibility` (`app`, `merchant`, `storefront`). |
| `data.definitions[].label` | Optional, `{ ar = "…", en = "…" }`: the name the dashboard shows next to a value. Not live yet, see [Marketplace fields](#marketplace-fields-not-live-yet). |
| `storefront.blocks` | Storefront blocks: see [Marketplace fields](#marketplace-fields-not-live-yet). Not live yet. |
| `offers.types` | Offer types a merchant can create from your app: see [Offer types](#offer-types). Needs `write_offers`. |
| `admin.actions` | Menu entries in the dashboard: see [Marketplace fields](#marketplace-fields-not-live-yet). Not live yet. |
| `app_proxy` | Part of the format, refused until the app proxy opens. |

* **Every table is strict:** a key that is not a manifest field is an error,
  and the error's `fix` names the field you probably meant.
* **Size:** at most 64 KB once parsed into JSON. Lengths count UTF-16 code
  units.
* **Paths are joined to `hosting.url`**, its own path kept: with
  `url = "https://sync.example.com/tassyir"`, `uri = "/hooks"` is
  `https://sync.example.com/tassyir/hooks`. A hosted app's paths are joined
  to its own address, `https://{handle}.tassyir-apps.com`.
* **Every host your data reaches** (`hosting.url`, an absolute webhook `uri`,
  `auth.callback_url`) is shown to the merchant on the install screen.

## Offer types

An app that runs offers of its own ([Write offers and codes](/guides/write-offers))
can declare **kinds of offer** the merchant creates from your app, under "From
your apps" on the Offers page:

```toml theme={null}
[[offers.types]]
handle      = "mix-match"
class       = "product"
path        = "/offers/mix-match"
label       = { ar = "اخلط واختر", en = "Mix and match" }
description = { ar = "القطعة الثالثة مجانًا", en = "The third piece free" }
```

At most 10 types, each with:

| Field | Rule |
| - | - |
| `handle` | Required. 1 to 40 lowercase letters, digits and hyphens, starting with a letter or digit. Once per manifest (`MANIFEST_OFFER_TYPE_HANDLE_DUPLICATE`) |
| `class` | Required. `product`, `order` or `delivery`: the step the offers of the type price in |
| `path` | Required. The page of your app that configures one offer of the type: a path on your origin (the `admin.page` rules, at most 200 characters; on a hosted app never `/.tassyir` or below) |
| `label` | Required. `{ ar = "…", en = "…" }`, 1 to 50 characters each (the `name` text rules) |
| `description` | Optional. `{ ar, en }`, 1 to 200 characters each |

Declaring any type needs the `write_offers` scope, in `scopes` or in
`optional_scopes` (`MANIFEST_OFFER_TYPES_SCOPE_MISSING`). The type declares
what the merchant can pick; the rule that prices each offer is written through
the Admin API, with `kind = "app"` ([Your own offer
types](/guides/write-offers#your-own-offer-types)).

## Marketplace fields (not live yet)

These fields belong to the marketplace, which is **not live yet**. The
validator in `@tassyir/app-manifest` already checks them, so you can prepare
a manifest now, but the API refuses an upload that uses any of them until the
marketplace opens: the fields are unknown to it, or `write_storefront` is not
offered yet. This page will say when that changes.

```toml theme={null}
name        = "Review Stars"
handle      = "review-stars"
api_version = "2026-10"

[access]
scopes = ["read_orders", "read_products", "write_storefront"]

[access.scope_reasons]
read_orders      = "Find delivered orders to ask for a review"
read_products    = "Show each product's rating"
write_storefront = "Add the rating block to your product pages"

[hosting]
mode = "external"
url  = "https://stars.example.com"

[admin]
page = "/"

[[admin.actions]]
handle = "ask-for-reviews"
target = "orders.selection"
label  = { ar = "اطلب التقييمات", en = "Ask for reviews" }
path   = "/actions/ask"

[[data.definitions]]
owner      = "product"
key        = "rating"
type       = "json"
visibility = "storefront"
label      = { ar = "التقييم", en = "Rating" }

[[storefront.blocks]]
handle     = "product-rating"
template   = "blocks/product-rating.liquid"
stylesheet = "blocks/product-rating.css"
name       = { ar = "تقييم المنتج", en = "Product rating" }
target     = "product"
data       = ["product.rating"]

  [[storefront.blocks.settings]]
  key     = "show_count"
  type    = "boolean"
  label   = { ar = "عرض عدد التقييمات", en = "Show the number of ratings" }
  default = true

  [[storefront.blocks.settings]]
  key     = "heading"
  type    = "string"
  label   = { ar = "العنوان", en = "Heading" }
  default = { ar = "آراء الزبائن", en = "What buyers say" }
```

### Labels

Text a merchant reads in the dashboard or the store builder is a table with
both languages, `{ ar = "…", en = "…" }`: a block's `name`, a setting's and an
option's `label`, an admin action's `label` and a data definition's `label`.
Each language follows the `name` rules (1 to 50 characters on one line, no
invisible character, no spaces around it), and no other key is accepted.

### Storefront blocks

A block is a template that Tassyir renders on the store's pages, where the
merchant places it from the store builder. It runs no JavaScript: a block
holds no script, and any key that would add code (`script`, `html`, `src`,
`on…`) is refused. Blocks need the `write_storefront` scope, at most 20 a
version.

| Field | Rule |
| - | - |
| `handle` | Required. The `handle` rules; unique among the app's blocks. |
| `template` | Required. A `.liquid` file of the app's files: a relative path of lowercase letters, digits, `_` and `-`, at most 200 characters. |
| `stylesheet` | Optional. A `.css` file, the same path rules. |
| `name` | Optional label: how the block is listed in the store builder. Write it: the review asks for one. |
| `target` | `product` (the product page; the template can read the page's product) or `any` (any page but the order form's, without a product). Default `any`. |
| `data` | At most 20 app data keys the template reads, each once, as `<owner>.<key>`: declared in `[[data.definitions]]` with `visibility = "storefront"`, the owner `business`, `store` or `product`. Order and customer data never reach a store page. Product data needs `target = "product"`. |
| `settings` | At most 20 `[[storefront.blocks.settings]]`: what the merchant sets for the block. |

### Block settings

The template reads a setting as `block.settings.<key>`. The store builder
draws the form from the declaration and checks every value against it.

| Field | Rule |
| - | - |
| `key` | Required. 1 to 40 lowercase letters, digits and underscores, starting with a letter; unique in the block. |
| `type` | Required. `string`, `text`, `boolean`, `integer`, `number`, `select`, `color`, `image`, `url`, `product` or `collection`. |
| `label` | Required label: the field's name in the store builder. |
| `default` | Optional, a value of the type (below). |
| `options` | `select` only, and required there: 2 to 20 `{ value, label }`. A `value` is 1 to 40 lowercase letters, digits, `_` and `-`, each once. |
| `min`, `max` | `integer` and `number` only: the range, `min` at most `max`; whole numbers for an `integer`. |
| `max_length` | `string` and `text` only: 1 to 1,000 characters (1,000 when absent). |

| Type | `default` |
| - | - |
| `string` | One line of text, or `{ ar = "…", en = "…" }` for each language, within `max_length`. |
| `text` | The same, line breaks allowed. |
| `boolean` | `true` or `false`. |
| `integer`, `number` | A whole number (`integer`) or a number, within `min` and `max`. |
| `select` | The `value` of one of its options. |
| `color` | `"#rrggbb"`. |
| `url` | An `https://` link or a path of the store starting with `/`, at most 512 characters, no space. |
| `image`, `product`, `collection` | None: the merchant picks one from their own store. |

```toml theme={null}
[[storefront.blocks.settings]]
key     = "layout"
type    = "select"
label   = { ar = "الشكل", en = "Layout" }
default = "grid"
options = [
  { value = "grid", label = { ar = "شبكة", en = "Grid" } },
  { value = "list", label = { ar = "قائمة", en = "List" } },
]
```

### Admin actions

`[[admin.actions]]` adds a menu entry on an order, product or customer page,
or on a selection in the orders or products list. Choosing it opens one of
the app's pages in the dashboard's app window, with the ids added to its
address (`?id=` or `?ids=`, at most 50): read them again through the Admin
API, where your scopes and the installation's stores apply. At most 10.

| Field | Rule |
| - | - |
| `handle` | Required. The `handle` rules; unique among the app's actions. |
| `target` | Required. `order.details`, `orders.selection`, `product.details`, `products.selection` or `customer.details`. It needs the read scope of its resource: `read_orders`, `read_products` or `read_customers`. |
| `label` | Required label: the menu entry. |
| `path` | Required. The page it opens: the `admin.page` rules. |

An app with actions does not need `admin.page`.

### The app proxy

`[app_proxy]` names the path on your app where Tassyir forwards requests made
to the store's own address, `https://{store}/apps/{handle}/…`. It needs the
`write_storefront` scope, and its `path` follows the `admin.page` rules. It is
part of the format but refused until the app proxy opens
(`MANIFEST_PROXY_NOT_AVAILABLE`), even by the validator.

```toml theme={null}
[app_proxy]
path = "/proxy"
```

## Validate before you upload

`@tassyir/app-manifest` is the validator the Tassyir API runs on every upload,
so a manifest it accepts is one the API accepts, with the same errors in the
same order. Parse the TOML with any TOML 1.0 parser, then validate:

```ts theme={null}
import { readFileSync } from 'node:fs';
import { parse } from 'smol-toml';
import { validateManifest } from '@tassyir/app-manifest';

const result = validateManifest(
  parse(readFileSync('tassyir.app.toml', 'utf8')),
);

if (!result.ok) {
  for (const error of result.errors) {
    console.error(
      `${error.code} at ${error.path || '(document)'}: ${error.fix}`,
    );
  }
  process.exit(1);
}

console.log(result.manifest.access.scopes); // in catalogue order
```

A project made with `create-tassyir-app` runs this as `npm run validate`
(`-- --json` for tools).

It returns every error at once, never throws, and reads no file, clock or
network. Each error has:

| Field | Meaning |
| - | - |
| `code` | Stable: `MANIFEST_TOPIC_SCOPE_MISSING`, `MANIFEST_URL_INVALID`, … Never renamed. |
| `path` | The field in the file: `webhooks[0].topics[1]`, `""` for the whole document. |
| `message` | What is wrong, quoting at most 60 characters of your input. |
| `fix` | One sentence saying what to change. |

```json theme={null}
{
  "code": "MANIFEST_TOPIC_SCOPE_MISSING",
  "path": "webhooks[0].topics[1]",
  "message": "\"products/updated\" carries data that needs the \"read_products\" scope, which the manifest does not request.",
  "fix": "Add \"read_products\" to `access.scopes` (or `access.optional_scopes`), or remove \"products/updated\"."
}
```

The same document always gives the same errors in the same order, whatever
the order of its keys: one per field, at most 50, then
`MANIFEST_TOO_MANY_ERRORS`. The package README lists every
[error code](https://github.com/tassyir/apps-sdk/tree/main/packages/app-manifest#what-you-get-back).

To check one field as it is typed (a handle in a form, say), use
`validateManifestField('handle', value)`.

### In your editor

The JSON Schema of the manifest ships with the package. In an editor that
reads schema directives (Taplo, Even Better TOML), start the file with:

```toml theme={null}
#:schema ./node_modules/@tassyir/app-manifest/schemas/manifest.2026-10.schema.json
```

The schema states the shape; the validator also checks the rules across
fields and the exact URL and hostname rules, so a file the schema accepts can
still be refused.

## Upload a version

In the developer console, open your app's **Versions** tab and upload the
file. The console sends the parsed manifest to the API, which validates it
again and:

* refuses it with every validator error (`APP_MANIFEST_INVALID`, each error in
  the shape above);
* refuses a `handle` other than the app's (`APP_MANIFEST_HANDLE_MISMATCH`), a
  manifest identical to the latest version (`APP_VERSION_UNCHANGED`), and
  `hosting.mode = "tassyir"` while hosting is closed
  (`APP_HOSTING_NOT_AVAILABLE`);
* otherwise numbers it (`1`, `2`, …) and makes it current at once. Custom
  apps are not reviewed: they install only on your own businesses and the one
  business you name.

Limits per developer account: 50 apps (apps are never deleted), 30 version
uploads an hour, and an upload of at most 128 KB.

A hosted version also carries its code: `tassyir deploy` builds it, checks
it and uploads both, then follows the scan every hosted version goes through
([Tassyir Hosting](/guides/tassyir-hosting#deploy-with-the-cli)).

**Installations do not move by themselves.** A new version is offered to each
installation as an update, and applies only when a member of that business
accepts it. A version that adds a scope or a new host asks for consent again.
See [Scopes and consent](/guides/scopes-and-consent#new-versions-and-updates).

## Versions of the format

The manifest's shape belongs to an API version. Within a version, only new
optional fields can be added; a release of `@tassyir/app-manifest` ships them,
and an older release refuses them until you update it.


# Offers
Source: https://developers.tassyir.io/guides/offers

Read the merchant's pricing offers with read_offers, follow them with the offers/* webhooks, and handle new kinds, store limits and codes you cannot see.

An offer is a price rule a merchant sets on one of their stores: "buy 2 and
save 900", free delivery over a threshold, a percentage off a product. It
applies by itself, or when the buyer types one of its codes. An app reads the
merchant's offers (a reports app that lines orders up with the offer that
priced them, an ads app that shows the live deal in a campaign, an assistant
that explains why a cart total is lower) and follows them with webhooks.

With `read_offers` an app **reads** offers. With `write_offers` it also runs
offers of its own, and their codes: that is [Write offers and
codes](/guides/write-offers). An app never changes the merchant's own offers, and
never applies an offer to an order itself.

| Route | Does | Scope |
| - | - | - |
| `GET /offers` | List offers | `read_offers` |
| `GET /offers/{id}` | Read one offer | `read_offers` |
| `offers/created`, `offers/updated` | Webhooks (an offer) | `read_offers` |
| `offers/deleted` | Webhook (an id) | `read_offers` |

Reading offers needs no particular plan of the merchant (the plan limits how
many offers can be live, not who can read them). `read_offers` is a normal
scope and implies no other. Like any scope added after an app was installed,
an installation does not hold it until the merchant accepts a version of your
app that asks for it ([Scopes and consent](/guides/scopes-and-consent)). A call
without it answers 403 `PERMISSION_DENIED`, with a `fix` that names the scope.

## The offer

```json theme={null}
{
  "id": "741000000000002000",
  "storeId": "741000000000000100",
  "kind": "quantity",
  "method": "automatic",
  "title": "Buy 2, save 900",
  "label": { "ar": "عرض الكمية", "fr": null, "en": null },
  "status": "active",
  "currency": "DZD",
  "quantity": {
    "priceMode": "total",
    "tiers": [
      {
        "pieces": 2,
        "label": { "ar": "قطعتان", "fr": null, "en": null },
        "total": "8900.00",
        "percentOff": null,
        "amountOffEach": null,
        "preselected": true,
        "freeDelivery": false
      }
    ]
  },
  "freeDelivery": null,
  "productDiscount": null,
  "combinesWith": { "product": false, "order": true, "delivery": true },
  "eligibility": {
    "audience": "everyone",
    "channels": [],
    "wilayas": [],
    "deliveryMethods": []
  },
  "targets": [{ "role": "buy", "type": "product", "id": "741000000000000500" }],
  "codeCount": 0,
  "totalUsageLimit": null,
  "perBuyerLimit": 1,
  "startsAt": "2026-10-01T00:00:00.000Z",
  "endsAt": null,
  "publishedAt": "2026-10-01T00:00:00.000Z",
  "pausedAt": null,
  "archivedAt": null,
  "appOwned": false,
  "createdAt": "2026-09-30T10:00:00.000Z",
  "updatedAt": "2026-10-02T10:00:00.000Z"
}
```

* **`method`** is `automatic` (applies by itself) or `code` (the buyer types one
  of the offer's codes).
* **`status`** is `draft` (never published), `scheduled` (starts later),
  `active`, `paused` or `ended` (past `endsAt`, or archived). It is worked out
  when the body is built, so a webhook body that is minutes old can be out of
  date: read the offer again when it matters.
* **`label`** is what the buyer reads, per language (`ar`, `fr`, `en`; a
  language the merchant did not fill is `null`). `title` is the merchant's own
  name for the offer.
* **`targets`** holds `{ role, type, id }` entries: `role` `buy` is what the
  offer applies to, and `type` is `all` (then `id` is `null`), `product`,
  `variant` or `collection`. Read a collection's products with
  `GET /products?collectionId=`
  ([Products and collections](/guides/products-and-collections)).
* **`combinesWith`** says whether the offer may stack with other product,
  order and delivery offers.
* **`eligibility`** limits who and where: `audience` is `everyone`,
  `first_order` or `returning`; `channels` are among `store`, `landing`,
  `shopify`, `dashboard` and `apps`, and `wilayas` and `deliveryMethods`
  (`home`, `desk`) narrow it further. **An empty list means no limit.**
* **`totalUsageLimit`** and **`perBuyerLimit`** are the limits the merchant
  set (`null` = none).
* **`appOwned`** is true for an offer that belongs to an installed app. Which
  installation is never shown.
* Money is a decimal string next to `currency` (`DZD`). Timestamps are ISO 8601
  in UTC.

## The kinds

`kind` says which one of seven fields holds the rule. The other six are
`null`:

| `kind` | Field | Reads |
| - | - | - |
| `quantity` | `quantity` | `priceMode` `total` (each tier's `total` is the whole price of `pieces` pieces), `percent` (`percentOff` off each piece) or `amount_each` (`amountOffEach` off each piece). Tiers go up by `pieces`; at most one is `preselected`; a tier's `freeDelivery` waives delivery at that tier |
| `free_delivery` | `freeDelivery` | The threshold: `thresholdKind` `pieces` (`thresholdPieces`) or `amount` (`thresholdAmount`), `null` while a draft has none; `delivery` `home`, `desk` or `both`; `wilayas` as two-digit codes, empty = every wilaya |
| `product_discount` | `productDiscount` | `valueType` `percent` (`percent`, with `maxAmount` capping the saving per unit) or `fixed` (`amount` off each unit); `showCountdown` counts down to `endsAt` |
| `order_discount` | `orderDiscount` | `valueType` `percent` (`percent`, with `maxAmount` capping the order's saving) or `fixed` (`amount` off the order); `minimumKind` `pieces` or `amount` (`minimumPieces`, `minimumAmount`), `null` = every order |
| `bxgy` | `bxgy` | Buy X, get Y: `buyPieces` paid pieces and `getPieces` discounted ones per set; `getDiscountType` `percent` (`getPercent`, 100 = free) or `fixed_price` (`getPrice` per piece); `maxPerOrder` sets, `null` = as many as the cart holds. The buy and get products are the `targets` with role `buy` and `get` (no `get` target: the buy products themselves) |
| `addon` | `addon` | A product offered next to the order: `priceType` `fixed_price` (`price`), `percent` or `amount_off` (`amountOff`); `maxQuantity`; `beforeSubmit` (in the order form) and `afterSubmit` (on the thank-you page). The add-on products are the `targets` with role `addon`, the products that trigger it role `buy` |
| `app` | `appRule` | An offer of an app's own type: `{ typeHandle, rule }`, where `rule` is the declarative rule the app wrote ([Write offers and codes](/guides/write-offers#the-rule)). It is the app's JSON, so read it defensively |

**`kind` can grow.** Tassyir adds kinds, and values to the other open fields
(`priceMode`, `valueType`, `audience`, a target's `type`), inside API version
`2026-10`. Write code that **ignores an offer of a kind it does not know**
(all seven rule fields are `null` for it) instead of failing, and treat every
field you do not know the same way:

```ts theme={null}
import type { Offer } from '@tassyir/app';

/** One line for a campaign, or null for a kind this code does not know. */
export function describe(offer: Offer): string | null {
  switch (offer.kind) {
    case 'quantity': {
      const tier = offer.quantity?.tiers.find((t) => t.preselected);
      return tier ? `${String(tier.pieces)} pieces` : null;
    }
    case 'free_delivery':
      return 'Free delivery';
    case 'product_discount':
      return offer.productDiscount?.percent
        ? `${String(offer.productDiscount.percent)}% off`
        : null;
    case 'bxgy':
      return offer.bxgy
        ? `Buy ${String(offer.bxgy.buyPieces)}, get ${String(offer.bxgy.getPieces)}`
        : null;
    case 'app':
      // The app's own rule: only its type is known to everyone.
      return offer.appRule?.typeHandle ?? null;
    default:
      // A kind added later.
      return null;
  }
}
```

## Codes and usage

**Codes are not exposed.** `codeCount` is the number of codes that can still
be used, and that is all an app learns about them. The codes and the
redemptions of an offer are read only by the app that **owns** the offer
([Write offers and codes](/guides/write-offers)). **No buyer or phone is ever
sent**, and using an offer at checkout sends no event. To know which orders an offer priced you need the orders
themselves, under their own scope: an order's `discounts[]` names the offer
that priced it ([Order money](/guides/orders#order-money)).

## List and read

`GET /offers` lists the offers newest first, **drafts and ended offers
included**, in pages
([Admin API conventions](/guides/admin-api#one-resource-and-lists)). Filters:

| Parameter | Rule |
| - | - |
| `status` | One of `draft`, `scheduled`, `active`, `paused`, `ended`. Omitted: all of them |
| `kind` | `quantity`, `free_delivery`, `product_discount`, `order_discount`, `bxgy`, `addon` or `app` |
| `method` | `automatic` or `code` |
| `storeId` | Only the offers of this store. A store outside the installation's is HTTP 460 `STORE_SCOPE_FORBIDDEN` |

A cursor belongs to the filters it was made with: use the same four on every
page, or `INVALID_CURSOR` answers 400. `GET /offers/{id}` answers one offer;
an id that does not exist, is malformed, or belongs to a store outside the
installation's is 404 `NOT_FOUND`.

```ts theme={null}
for await (const offer of admin.paginate('/offers', {
  query: { status: 'active', method: 'automatic' },
})) {
  console.log(offer.storeId, offer.title, `${offer.kind}`);
}

const { data: offer } = await admin.get('/offers/{id}', {
  path: { id: '741000000000002000' },
});
console.log(offer.status, offer.endsAt);
```

## Stores

An offer belongs to exactly **one store**. An installation limited to
selected stores reads the offers of those stores only, and the offers of any
other store read as 404. Its webhooks follow the same rule: **every offer
event carries the offer's store**, so a store-limited installation hears the
events of its own stores and no others. An installation with every store
hears them all.

## Webhooks

Subscribe to the topics in the manifest, with the scope that reads them
([Webhooks](/guides/webhooks)):

```toml theme={null}
[[webhooks]]
topics = ["offers/created", "offers/updated", "offers/deleted"]
uri    = "/webhooks"
```

* `offers/created` is sent when an offer is created, with `data.offer` (the
  offer above). **A new offer is always a draft**: you hear `offers/updated`,
  with `changed` naming `status` and `publishedAt`, when it goes live.
* `offers/updated` is sent when the offer reads differently: publishing,
  pausing, archiving, its dates, its rules, its targets or its codes.
  `changed` names the top-level fields that differ (`status`, `pausedAt`,
  `endsAt`, `quantity`, `targets`, `codeCount`, …), and `data.offer` is the
  offer as it is now. A change that alters nothing an app can read sends
  nothing.
* `offers/deleted` is sent when an offer is deleted, with
  `data.offer = { "id": … }` and nothing else. Only an offer that was
  **never redeemed** can be deleted: a redeemed one is archived, which is
  `offers/updated` with `status: "ended"` and `archivedAt` set.

Deliveries are at least once and unordered: deduplicate on `webhook-id`, and
when two bodies of one offer arrive out of order, keep the one with the later
`updatedAt`.

```ts theme={null}
import type { WebhookEvent } from '@tassyir/app';

/** Keeps a local copy of the merchant's offers. */
export async function onOfferEvent(
  event: WebhookEvent,
  store: {
    save(id: string, offer: object): Promise<void>;
    remove(id: string): Promise<void>;
  },
): Promise<void> {
  switch (event.type) {
    case 'offers/created':
    case 'offers/updated': {
      const { offer } = event.data;
      // Keep the body even for a kind you do not understand: it is the truth.
      await store.save(offer.id, offer);
      break;
    }
    case 'offers/deleted':
      await store.remove(event.data.offer.id);
      break;
    default:
      break;
  }
}
```

## What is not here yet

Creating offers, their codes (in bulk) and a list of redemptions, and offer
types that belong to your app, are in [Write offers and
codes](/guides/write-offers). No app code runs at checkout: an app-owned offer is a
declarative rule that Tassyir evaluates.


# Orders
Source: https://developers.tassyir.io/guides/orders

Read a business's orders, keep them in sync, and create, edit, confirm, cancel, schedule and comment on them like a team member.

An app works orders the way a team member does: it reads them, creates
orders from its own channel, fixes the buyer's details, confirms, cancels
with a reason, schedules a call back and leaves comments. Every write runs the
same checks as the dashboard button that does the same thing, and the
dashboard shows your app's name on it ("Review Requests confirmed order
\#1042").

| Route | Does | Scope |
| - | - | - |
| `GET /orders`, `GET /orders/{id}` | List and read orders | `read_orders` |
| `GET /orders/{id}/comments` | Read an order's comments | `read_orders` |
| `GET /cancel-reasons` | The business's cancel reasons | `read_orders` |
| `POST /orders` | Create an order | `write_orders` |
| `PATCH /orders/{id}` | Edit the buyer, delivery and notes | `write_orders` |
| `POST /orders/{id}/confirm` | Confirm | `write_orders` |
| `POST /orders/{id}/cancel` | Cancel, with an optional reason | `write_orders` |
| `POST /orders/{id}/schedule` | Schedule a call back | `write_orders` |
| `POST /orders/{id}/comments` | Add a comment | `write_orders` |

Dispatching to a carrier, labels and returns are not in API version
`2026-10`.

## The order

```json theme={null}
{
  "id": "741000000000000001",
  "orderNumber": "1042",
  "storeId": "741000000000000100",
  "status": "confirmed",
  "waiting": false,
  "archived": false,
  "dispatched": false,
  "delivered": false,
  "returned": false,
  "currency": "DZD",
  "total": "5000.00",
  "shippingPrice": "500.00",
  "subtotal": "5000.00",
  "discountTotal": "500.00",
  "discounts": [
    {
      "title": "Autumn sale",
      "code": null,
      "class": "product",
      "source": "offer",
      "amount": "500.00",
      "offerId": "741000000000000800"
    }
  ],
  "buyer": {
    "provinceCode": 16,
    "townOns": 1601,
    "name": "Amina B.",
    "phone": "+213555123456"
  },
  "delivery": {
    "method": "home",
    "speed": "standard",
    "deliveryAgentId": null,
    "trackingNumber": null,
    "carrierStatus": null
  },
  "items": [
    {
      "id": "741000000000000011",
      "productId": "741000000000000500",
      "variantId": "741000000000000501",
      "packParentItemId": null,
      "name": "Robe kabyle",
      "variantName": "M",
      "sku": "RK-01-M",
      "quantity": 1,
      "unitPrice": "4500.00",
      "totalPrice": "4500.00",
      "originalPrice": "5000.00",
      "discountAmount": "500.00",
      "discounts": [
        {
          "title": "Autumn sale",
          "code": null,
          "class": "product",
          "source": "offer",
          "amount": "500.00",
          "offerId": "741000000000000800"
        }
      ]
    }
  ],
  "source": "app:review-requests",
  "confirmedAt": "2026-10-11T09:12:44.120Z",
  "createdAt": "2026-10-11T08:00:00.000Z",
  "updatedAt": "2026-10-11T09:12:44.120Z"
}
```

* **State:** `status` is the pipeline status, built in (`pending`,
  `confirmed`, `scheduled`, `canceled`, …) or one the merchant named: treat it
  as an open string. The flags `dispatched`, `delivered`, `returned`,
  `archived` and `waiting` say the rest. **A returned order keeps its status**
  (usually `pending`): read `returned`.
* **Money:** `total`, `shippingPrice`, `subtotal`, `discountTotal`, and each
  line's `unitPrice`, `totalPrice`, `originalPrice` and `discountAmount` are
  decimal strings in `currency`; `discounts[]` says which offers priced the
  order ([Order money](#order-money)).
* **Buyer:** `provinceCode` (the wilaya, 1 to 58) and `townOns` (the commune)
  always; `name`, `phone`, `phone2`, `email`, `address`, `address2`, and the
  order's `note` and `deliveryNote`, only with `read_customer_contact`.
* **Delivery:** `method` (`home` or `stopdesk`), `speed`, the delivery agent,
  the tracking number and `carrierStatus`, the carrier's own wording.
* **Lines:** `items[]`; a pack's component lines carry `packParentItemId`.
* **Where it came from:** `source` (`shopify:<domain>`, `app:<handle>` for an
  order an app created, `null` for the storefront and the dashboard),
  `landingPageId`, `utm { source, medium, campaign, content }`.
* **Other:** `exchangeOfOrderId`, `cancellation { reasonId, reasonLabel,
  source }`, and the times `scheduledFor`, `confirmedAt`, `dispatchedAt`,
  `deliveredAt`, `returnedAt`, `canceledAt`, `createdAt`, `updatedAt`.

**Waiting orders.** An order past the plan's order allowance is created
`waiting: true` and masked whatever your scopes (phones `**********`, notes
`null`) until it unlocks, which sends `orders/updated` with `waiting`. You may
read, edit, cancel, schedule and comment on it; confirming it is 403
`ORDER_LIMIT_REACHED`.

## Order money

Read an order's money in this order: the goods before any offer, what the
offers took off, what the buyer pays for delivery, and what the courier
collects.

| Field | Meaning |
| - | - |
| `subtotal` | The goods before every offer. Always present. An order with no discount data (older orders, exchanges, orders synced from another channel) reads `total − shippingPrice`. |
| `discountTotal` | What the product and order discounts took off. `"0.00"` when none. It **leaves out** a delivery waiver. |
| `shippingPrice` | What the buyer pays for delivery: `"0.00"` when it was waived. |
| `total` | What the courier collects: `subtotal − discountTotal + shippingPrice`. |
| `discounts[]` | Every discount the order got, one entry per title, code, class and source. |
| `items[].originalPrice` | The catalogue unit price before any offer. `null` on a line no discount was worked out for (older orders, exchanges, synced orders). |
| `items[].discountAmount` | The line's share of the product and order discounts. `"0.00"` when none. |
| `items[].discounts[]` | The `product` entries that priced this line. |

A `discounts[]` entry is `{ title, code, class, source, amount, offerId }`:

* `title` is the offer or code's name, frozen when the order was placed: it
  does not follow a later rename.
* `class` is `product` (taken off lines), `order` (taken off the whole order)
  or `delivery` (the delivery waiver, which is **not** part of `discountTotal`).
* `source` is `offer`, `code`, `manual`, `app` or `import`; treat it as an open
  string. `code` is the code the buyer typed, if any.
* `offerId` is `null` for a manual, imported or older quantity-tier discount.
  Read the offer through [Offers](/guides/offers) when it is set.

**Lines are net.** A line's `unitPrice` and `totalPrice` are what was charged
after the discounts; `originalPrice` is the gross unit price. For an order
priced with discounts, `totalPrice = originalPrice × quantity − discountAmount`,
`unitPrice = totalPrice / quantity`, and `discountTotal` is the sum of the
lines' `discountAmount`. A discount that covers several lines is spread over
them, so a line's `totalPrice` is its own amount, never the whole offer's.

**"You saved"** is `discountTotal` plus the `amount` of the entries with
`class: "delivery"`. Add them with a decimal library, never `parseFloat`.

```ts theme={null}
const { data: order } = await admin.get('/orders/{id}', {
  path: { id: '741000000000000001' },
});

for (const item of order.items) {
  if (item.discountAmount === '0.00') continue;
  const offers = item.discounts.map((discount) => discount.title).join(', ');
  console.log(
    `${item.name}: ${item.originalPrice ?? '?'} → ${item.unitPrice ?? '?'} (${offers})`,
  );
}
console.log('goods', order.subtotal, 'off', order.discountTotal);
```

The fields come with or without `read_customer_contact`, and on a waiting
order: money carries no contact data. `fields` accepts `subtotal`,
`discountTotal` and `discounts`. The `orders/*` webhook bodies carry the same
fields, and a change to one of them (a discount added or removed on an edit)
sends `orders/updated` with `changed` naming `subtotal`, `discountTotal` or
`discounts`: if you switch over `changed`, keep a default branch. An abandoned
checkout's lines carry `originalPrice`, `discountAmount` and `discounts`, but
the checkout itself has no order-level money fields.

## Which orders you can reach

`GET /orders` lists every order of the business your token may read: every
stage, archived ones included, newest first. Not listed: abandoned checkouts
still waiting for the merchant (they are `abandoned_checkouts/created`, and
become orders when recovered) and the collected-goods rows Tassyir keeps
for an exchange. Orders of stores outside your installation's are left out.

Every route that names an order reads it that way first: any other id is
**404 `NOT_FOUND`**, before anything is written. With an online token whose
person may see only the orders assigned to them, you reach only those.

## List and sync

| Filter | Rule |
| - | - |
| `status` | One status or several, comma-separated (`confirmed,scheduled`): 1 to 20, custom statuses by name. |
| `createdSince` | ISO 8601 (`2026-10-01T00:00:00Z`; a date alone is midnight UTC): created at or after it. |
| `updatedSince` | Changed at or after it, carrier tracking included. |
| `storeId` | One of your installation's stores; another is 460. |

Filters only narrow, and the cursor is bound to them. The list stays ordered
by creation, so to sync **walk every page and keep the largest `updatedAt`
you saw**, then start the next sync from it:

```ts theme={null}
export async function syncOrders(since: string): Promise<string> {
  let newest = since;
  for await (const order of admin.paginate('/orders', {
    query: { updatedSince: since, limit: 100 },
  })) {
    // Upsert the order in your own store here, by id.
    if (order.updatedAt > newest) newest = order.updatedAt;
  }
  return newest; // where the next sync starts
}
```

Between syncs, the `orders/*` webhooks tell you what changed
([Webhooks](/guides/webhooks#how-events-are-recorded)).

## Create an order

```ts theme={null}
const created = await admin.request('post', '/orders', {
  body: {
    storeId: '741000000000000100',
    buyer: {
      name: 'Amina B.',
      phone: '+213555123456',
      provinceCode: 16,
      townOns: 1601,
      address: '12 rue Didouche Mourad',
    },
    items: [
      {
        productId: '741000000000000500',
        variantId: '741000000000000501',
        quantity: 2,
      },
    ],
    delivery: { method: 'home', speed: 'standard' },
    note: 'Call after 6pm',
  },
  // One key per order of your channel: a retry never creates it twice.
  idempotencyKey: 'sheet-row-128',
});

if (created.status === 201)
  console.log('created', created.data.data.orderNumber);
else
  console.log(
    'the same buyer already ordered these items',
    created.data.data.id,
  );
```

| Field | Rule |
| - | - |
| `storeId` | Optional for an installation with one store or every store (then resolved from the items). Required with several selected stores (400 `STORE_REQUIRED`). |
| `buyer` | Required, may be `{}`. `phone`, `phone2`: `+213`, then 5, 6 or 7, then 8 digits. `provinceCode` 1 to 58, `townOns` a commune code, `name` up to 200, `address` and `address2` up to 500, `email`. |
| `items` | 1 to 50 lines of `productId`, optional `variantId`, `quantity` 1 to 999. Each product must be one you can list; same lines are merged. |
| `delivery` | Optional. `method`: `home` (default) or `stopdesk` (the desk of the buyer's commune). `speed`: `standard` (default) or `economy`. |
| `codes` | Optional, **one offer code at most** (`["SARA10"]`). A code that does not apply never fails the order: it is listed in `rejectedCodes` beside `data` ([Write offers and codes](/guides/write-offers#applying-a-code-to-an-order)). |
| `note`, `deliveryNote` | Optional, up to 1,000 characters. |

Anything else is refused, on purpose: an order is created `pending` (confirm
it with the route below), priced from the catalogue and the business's
delivery prices, never from your numbers, and carries no carrier, tracking,
payment or attribution of your choosing.

What happens is what happens to an order a merchant types in the dashboard:

* **The duplicate rule.** A second order for the same phone and the same
  items, within 24 hours and not yet dispatched, is folded into the first:
  **200** with that order, nothing created. If you cannot read that order,
  409 `ORDER_DUPLICATE`.
* **An abandoned checkout becomes the order.** When the buyer (same phone)
  left a checkout sharing a product, the order takes the checkout's id.
* **The business's distribution assigns it** to a team member, once.
* **The plan's allowance admits it**: past it, the order is created
  `waiting`, and your answer is masked.
* Its `source` is `app:<your handle>`, and `orders/created` is sent once.
* The storefront's anti-spam checks do not apply: your app is an
  authenticated member of the business, not a buyer's browser.

Answers: **201** for a new order (or a recovered checkout), **200** for an
existing one. With an `Idempotency-Key`, a retry replays the stored answer
and its status.

## Edit, confirm, cancel, schedule

```ts theme={null}
const id = '741000000000000001';

await admin.patch('/orders/{id}', {
  path: { id },
  body: { buyer: { townOns: 1602 }, deliveryNote: null },
});

const { data: reasons } = await admin.get('/cancel-reasons');
const noAnswer = reasons.find((reason) => !reason.requireNote);

await admin.post('/orders/{id}/schedule', {
  path: { id },
  body: { scheduledFor: '2026-10-20T09:00:00Z' },
});

await admin.post('/orders/{id}/cancel', {
  path: { id },
  body: noAnswer
    ? { reasonId: noAnswer.id }
    : { note: 'Buyer cancelled by phone' },
});
```

* **`PATCH`** changes `buyer` (only the keys you send), `delivery` (`method`,
  `speed`), `note` and `deliveryNote` (`null` clears one). Not the status, the
  store or the items. A new commune, method or speed re-prices the delivery.
  A dispatched, delivered or returned order is 409 `ORDER_NOT_EDITABLE`. It
  sends `orders/updated`.
* **`confirm`** (no body) checks the buyer's details for a carrier: a missing
  phone, wilaya or commune is a 400 naming `missingFields`. An empty address
  is filled from the commune. Sends `orders/confirmed`. Refusals: 403
  `ORDER_LIMIT_REACHED` (a waiting order), 409 `ORDER_STATUS_CONFLICT` (its
  status does not allow it, already confirmed included).
* **`cancel`** takes an optional `reasonId` (from `GET /cancel-reasons`) and
  `note` (up to 500). An archived or unknown reason is 400
  `CANCEL_REASON_INVALID`; a reason that requires a note, without one, 400
  `CANCEL_NOTE_REQUIRED`. Sends `orders/cancelled`.
* **`schedule`** takes `scheduledFor`, in the future: the status becomes
  `scheduled`. An order already scheduled is 409 `ORDER_STATUS_CONFLICT`.
  Sends `orders/updated`.

Every answer is the order, read again (`fields` trims it).

## Comments

`GET /orders/{id}/comments` lists the team's notes on the order, newest
first; `POST` adds one from your app (`{ "body": "…" }`, 1 to 1,000
characters).

```json theme={null}
{
  "id": "741000000000007002",
  "orderId": "741000000000000001",
  "byThisApp": true,
  "body": "Risk score 12/100",
  "createdAt": "2026-10-12T08:00:00.000Z",
  "updatedAt": "2026-10-12T08:00:00.000Z"
}
```

`byThisApp` marks your own comments; who else wrote one is not said. The team
often types phone numbers into comments, so another author's `body` follows
the notes rule: present only with `read_customer_contact`, and `null` while
the order is waiting. Your own comments always carry their body. Comments
send no webhook.

## Attribution

Every write is recorded in the activity log under your app's name, whatever
the token kind. An app's write never counts as a team member working the
order, and earns no commission.

## Errors these routes add

| Status | Code | When |
| - | - | - |
| 409 | `ORDER_NOT_EDITABLE` | The order is dispatched, delivered or returned. |
| 409 | `ORDER_STATUS_CONFLICT` | Its status does not allow the move. |
| 409 | `ORDER_DUPLICATE` | A create folded into an order you cannot read. |
| 403 | `ORDER_LIMIT_REACHED` | Confirming a waiting order. |
| 400 | `STORE_REQUIRED` | Several selected stores and no `storeId`. |
| 400 | `CANCEL_REASON_INVALID`, `CANCEL_NOTE_REQUIRED` | The cancel reason rules. |
| 400 | `DELIVERY_SPEED_UNAVAILABLE` | Economy is not priced for that destination. |

See [Errors](/guides/errors) for the codes every route shares.


# Products and collections
Source: https://developers.tassyir.io/guides/products-and-collections

Read and change the merchant's catalogue, bring images onto the Tassyir CDN, and organise collections.

An app manages the catalogue like a team member: it lists and reads products,
creates them, edits their copy, prices, images, options and variants, changes
one variant's price or SKU, and organises collections. Every write runs the
dashboard's own product and collection editors' checks, and is recorded under
your app's name.

| Route | Does | Scope |
| - | - | - |
| `GET /products`, `GET /products/{id}` | List and read products | `read_products` |
| `POST /products` | Create a product | `write_products` |
| `PATCH /products/{id}` | Change a product | `write_products` |
| `PATCH /products/{id}/variants/{variantId}` | Change one variant | `write_products` |
| `GET /collections`, `GET /collections/{id}` | List and read collections | `read_products` |
| `POST /collections`, `PATCH /collections/{id}` | Create and change a collection | `write_products` |
| `PATCH /collections/{id}/products` | Add and remove products | `write_products` |
| `DELETE /collections/{id}` | Delete a collection | `write_products` |
| `POST /images` | Bring an image onto the Tassyir CDN | `write_products` |

No route deletes a product: set `active: false` to take one off the store.
Stock is its own resource ([Stock](/guides/stock)), and so is the buy price
(`read_costs`).

## The product

```json theme={null}
{
  "id": "741000000000000500",
  "storeId": "741000000000000100",
  "name": "Robe kabyle",
  "slug": "robe-kabyle",
  "description": "<p>Faite main à Tizi Ouzou.</p>",
  "type": "PHYSICAL",
  "active": true,
  "visible": true,
  "currency": "DZD",
  "price": "4500.00",
  "compareAtPrice": "5200.00",
  "sku": "RK-01",
  "barcode": null,
  "image": "https://cdn.tassyir.io/images/0f1e2d3c/public",
  "images": ["https://cdn.tassyir.io/images/0f1e2d3c/public"],
  "weightKg": 0.6,
  "dimensionsCm": { "width": 30, "height": 5, "length": 40 },
  "tracksInventory": true,
  "allowOutOfStockOrders": false,
  "collectionIds": ["741000000000000600"],
  "brandId": null,
  "options": [{ "name": "Taille", "values": ["S", "M"] }],
  "variants": [
    {
      "id": "741000000000000501",
      "name": "M",
      "sku": "RK-01-M",
      "barcode": null,
      "price": "4700.00",
      "compareAtPrice": null,
      "image": null,
      "isDefault": false,
      "hidden": false,
      "options": [{ "name": "Taille", "value": "M" }],
      "createdAt": "2026-10-02T10:00:00.000Z",
      "updatedAt": "2026-10-02T10:00:00.000Z"
    }
  ],
  "createdAt": "2026-10-02T10:00:00.000Z",
  "updatedAt": "2026-10-03T10:00:00.000Z"
}
```

* `type` is `PHYSICAL` or `PACK` (a bundle of other products); an open
  string. `active` is false once the product is taken off the store.
* Every product has a **default variant** (`isDefault`) that follows the
  product's own name, image, SKU, barcode and prices. A product with options
  has one more variant per combination of option values.
* Deleted variants and options are left out.

## List and read

`GET /products` lists every product of your installation's stores, **active
or not**, newest first. Filters: `storeId`, `collectionId` (the collection's
members), `active` (`true` or `false`), `createdSince`, `updatedSince`. A
collection membership change does **not** move `updatedAt`: listen to
`products/updated`, which names `collectionIds`.

## Images on the storefront

A product's images and description are loaded by every buyer's browser on the
store, the page that holds the order form. So an app may only write images
that are:

* **on the Tassyir CDN**: `https://cdn.tassyir.io/…`; or
* **already shown by the same product or collection** (its image, gallery,
  variant images or description images), so rewriting a product keeps the
  merchant's own images.

Anything else is 400 `MEDIA_URL_NOT_ALLOWED` (`field`, `url`).

A **description** is HTML: paragraphs, headings, lists, emphasis, links and
CDN images. Refused with 400 `HTML_NOT_ALLOWED` (`field`, `problems`):
`<script>`, `<style>`, `<link>`, `<meta>`, `<base>`, frames, `<object>`,
`<embed>`, forms and their fields, `<template>`, any `on…` attribute,
`srcdoc`, `ping`, links that are not `http`, `https`, `mailto` or `tel` (or
that start with `//`), and inline CSS that can load something (`url(`,
`@import`, `image-set(`). `null` or `""` clears a description.

### Bring an image onto the CDN

An image from elsewhere (a supplier's feed, another platform) goes through
`POST /images` first. Tassyir downloads it, keeps it only if it is a JPEG,
PNG, GIF or WebP, stores it on its CDN in the merchant's media library, and
answers the URL the catalogue writes accept.

```ts theme={null}
/** One Idempotency-Key per image: a retry with the same key never uploads it twice. */
export async function uploadImage(
  sourceUrl: string,
  idempotencyKey: string,
): Promise<string> {
  const { data } = await admin.post('/images', {
    body: { url: sourceUrl },
    idempotencyKey,
  });
  return data.url; // https://cdn.tassyir.io/images/…
}

const image = await uploadImage(
  'https://images.example-shop.com/p/red-shoe.jpg',
  'image:red-shoe:main',
);
await admin.post('/products', {
  body: {
    storeId: '741000000000000100',
    name: 'Red shoe',
    price: '3200.00',
    image,
  },
});
```

```json theme={null}
{
  "data": {
    "id": "741000000000029500",
    "url": "https://cdn.tassyir.io/images/5c1d-77aa/public",
    "contentType": "image/jpeg",
    "sizeBytes": 184213,
    "width": 1200,
    "height": 1600
  }
}
```

Put `url` as it is in a product's `image` or `images`, a variant's `image`, a
collection's `image`, or an `<img src>` of a description. `id` is the image
in the merchant's media library, where it shows your app as its source. An
image already on `https://cdn.tassyir.io/` needs no upload.

| Refusal | Why |
| - | - |
| 400 `IMAGE_URL_NOT_ALLOWED` | The address, by its `reason`: `malformed`, `not_https`, `port` (only 443), `credentials`, `host` (an IP address, a single label, a private name), `tassyir_host`. |
| 400 `IMAGE_FETCH_FAILED` | The download, by its `reason`: `unreachable`, `timeout` (15 seconds), `tls`, `redirects` (more than 3), `http_status` (with `httpStatus`). |
| 400 `IMAGE_TYPE_NOT_ALLOWED` | Not a JPEG, PNG, GIF or WebP, judged by the bytes (`detected`). **SVG is always refused**: convert it to PNG. AVIF and HEIC are refused too. |
| 400 `IMAGE_TOO_LARGE` | Over 10 MB, or over 12,000 pixels on a side or 100 megapixels. |
| 429 `IMAGE_QUOTA_REACHED` | A quota window is full (below): `per`, `window`, `limit`, `Retry-After`. |
| 503 `SERVICE_UNAVAILABLE` | Tassyir could not store it now: retry later with the same `Idempotency-Key`. |

#### Limits

| Window | Limit | On a dev store |
| - | - | - |
| per installation, per UTC day | 1,000 | 100 |
| per business (all its apps together), per UTC day | 2,000 | 200 |
| per installation, per minute | 30 | 30 |

A download that was attempted counts, whatever it found. Send an
`Idempotency-Key` per image: a retry with the same key answers the same image
without downloading or counting it again.

`@tassyir/app` never retries 429 `IMAGE_QUOTA_REACHED`, even with retries
on: the error comes back at once, and its `problem` says which quota is full
(`per`, `window`: `day` or `minute`, `limit`, `retryAfter`), so your app can
wait out a minute window or stop for the day.

A raw file upload (multipart) is not offered yet: host the file somewhere
first.

## Create a product

```ts theme={null}
const { data: product } = await admin.post('/products', {
  body: {
    storeId: '741000000000000100',
    name: 'Robe kabyle',
    price: '4500.00',
    image: 'https://cdn.tassyir.io/images/0f1e2d3c/public',
    description: '<p>Faite main à Tizi Ouzou.</p>',
    options: [{ name: 'Taille', values: ['S', 'M'] }],
    variants: [
      {
        options: [{ name: 'Taille', value: 'S' }],
        price: '4500.00',
        sku: 'RK-01-S',
      },
      {
        options: [{ name: 'Taille', value: 'M' }],
        price: '4700.00',
        sku: 'RK-01-M',
      },
    ],
  },
});
console.log(product.id, product.variants.length);
```

| Field | Rule |
| - | - |
| `storeId`, `name`, `price`, `image` | Required. `name` 1 to 255 characters; `image` follows the image rule (the dashboard requires a main image too). |
| `price`, `compareAtPrice` | Decimal strings, at most two decimals, never negative (`"2500"`, `"2500.50"`), in dinars. |
| `description` | HTML, up to 200,000 characters, per the description rule. |
| `slug` | The product's URL segment, up to 120 characters; made from the name when omitted. One taken in the store is 409 `PRODUCT_SLUG_TAKEN`. |
| `sku`, `barcode` | Up to 100 characters, or `null`. |
| `images` | The gallery, up to 50, in display order. |
| `weightKg`, `dimensionsCm` | Numbers from 0 to 10,000, or `null`; dimensions all three or none. |
| `active`, `visible`, `allowOutOfStockOrders` | Booleans, `true` by default. |
| `brandId`, `collectionIds` | A brand of the store; up to 100 collections of the store to pick the product into. |
| `options`, `variants` | Up to 3 options of 1 to 100 values; with options, `variants` has every combination exactly once (up to 200), each with its `price`. |

Any other field (`tracksInventory`, `type`, `tags`, …) is 400
`VALIDATION_FAILED`. The option and variant rules refuse with their own codes
(`PRODUCT_VARIANT_COUNT_MISMATCH`, `PRODUCT_VARIANT_MISSING_COMBINATIONS`,
`PRODUCT_OPTION_DUPLICATE_VALUE`, …) and `details`. The answer is **201** with the
product read again, and `products/created` is sent.

## Change a product

`PATCH /products/{id}` saves the fields you send (the create's, but not
`storeId` or `collectionIds`); `null` clears the nullable ones.

* **`options` and `variants` replace the product's**, as the dashboard's
  editor saves them: send `options` with every value and `variants` with every
  combination. A variant with an `id` keeps that variant and changes only the
  fields you send; one without `id` is new and needs `price`; a variant left
  out is removed. `variants` alone keeps the options.
* A product may keep the outside images it already shows.

To change **one variant** without sending them all, use
`PATCH /products/{id}/variants/{variantId}` with any of `name`, `sku`,
`barcode`, `price`, `compareAtPrice`, `image`, `hidden`:

```ts theme={null}
const { data: variant } = await admin.patch(
  '/products/{id}/variants/{variantId}',
  {
    path: { id: '741000000000000500', variantId: '741000000000000501' },
    body: { price: '4900.00', compareAtPrice: null },
  },
);
console.log(variant.price);
```

Two apps changing two variants of one product never overwrite each other. A
variant added or removed meanwhile makes the save fail with
`PRODUCT_VARIANT_COUNT_MISMATCH`: read the product again and retry. The default
variant follows its product: 409 `PRODUCT_DEFAULT_VARIANT`, change the
product instead.

## Collections

A collection holds the products picked by hand, plus those matching its
conditions, minus those excluded by hand. Its page lists them in
`productSort` order.

```json theme={null}
{
  "id": "741000000000000600",
  "storeId": "741000000000000100",
  "parentId": null,
  "name": "Soldes",
  "description": null,
  "image": null,
  "active": true,
  "sortOrder": 2,
  "productSort": "NEWEST",
  "ruleMatch": "ALL",
  "rules": [
    {
      "field": "ON_SALE",
      "operator": "IS_TRUE",
      "valueRefIds": [],
      "valueNumber": null,
      "valueNumberMax": null,
      "valueText": null
    }
  ],
  "productsCount": 7,
  "createdAt": "2026-10-02T10:00:00.000Z",
  "updatedAt": "2026-10-03T10:00:00.000Z"
}
```

* `parentId` nests a collection under another of the same store.
* `productSort`: `UPDATED`, `NEWEST`, `OLDEST`, `PRICE_ASC`, `PRICE_DESC`,
  `NAME_ASC`, `NAME_DESC` or `MANUAL` (an open string).
* **Conditions:** `ruleMatch` (`ALL` or `ANY`, `null` without rules) and up to
  10 `rules`: `field` `BRAND` or `TAG` (with `valueRefIds`), `PRICE`
  (`valueNumber`, and `valueNumberMax` for `BETWEEN`, in dinars), `ON_SALE`,
  `TITLE` (`valueText`); `operator` `IS`, `IS_NOT`, `LESS_THAN`, `MORE_THAN`,
  `BETWEEN`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `IS_TRUE`, `IS_FALSE`.
* To list its products: `GET /products?collectionId=<id>`.

```ts theme={null}
const { data: sale } = await admin.post('/collections', {
  body: {
    storeId: '741000000000000100',
    name: 'Soldes',
    ruleMatch: 'ALL',
    rules: [{ field: 'ON_SALE', operator: 'IS_TRUE' }],
  },
});

await admin.patch('/collections/{id}/products', {
  path: { id: sale.id },
  body: { add: ['741000000000000500'], remove: ['741000000000000501'] },
});
```

* `PATCH /collections/{id}/products`: `add` picks products by hand (and lifts
  an exclusion), `remove` takes them out whatever put them there. Up to 250
  ids each, products of the collection's store. Each product that entered or
  left sends `products/updated` with `collectionIds`.
* `DELETE /collections/{id}`: its products stay in the catalogue, and its
  subcollections move up one level.
* Collections send no webhook of their own.

## Errors these routes add

| Status | Code | When |
| - | - | - |
| 400 | `MEDIA_URL_NOT_ALLOWED` | An image is not on the Tassyir CDN and not already on the resource. |
| 400 | `HTML_NOT_ALLOWED` | A description carries markup apps may not write. |
| 409 | `PRODUCT_DEFAULT_VARIANT` | A write to the variant that follows its product. |
| 409 | `PRODUCT_SLUG_TAKEN` | Another product of the store has that slug. |
| 400 | `IMAGE_*`, 429 `IMAGE_QUOTA_REACHED` | `POST /images` ([above](#bring-an-image-onto-the-cdn)). |

The catalogue's own codes (options, variants, collections, brands) reach you
unchanged, with their details.


# Publishing to the marketplace
Source: https://developers.tassyir.io/guides/publishing

List your app in the Tassyir app marketplace. The listing, the developer terms, the review checklist, which new versions go back to a person, and ratings.

**Not open yet.** The marketplace opens to merchants once its first apps are
reviewed. The listing, the checks and the submission below are live in the
API, so you can prepare your app now; until the opening, a submission may
wait longer than the turnaround Tassyir aims at. Ratings come after the
opening.

Every app starts as a **custom** app: it installs on its developer's own
businesses, or on the one business it names, and needs no review. To offer it
to every Tassyir merchant, you list it:

| Distribution | Who installs it | Review |
| - | - | - |
| `custom` | Your own businesses, or the one business the app names | None |
| `public` | Any business: browsed and searched in the marketplace | Yes |
| `unlisted` | Any business with the app's link (`apps.tassyir.io/<locale>/<handle>`) | Yes |

A listing is shown under Tassyir's name, so a person at Tassyir approves it
before merchants see it. Most of the review is automated: you can run the
same checks yourself, as often as you need, before you submit.

## The steps

1. Deploy the version you want listed (`tassyir deploy`), with the
   [compliance topics](/guides/compliance-and-uninstall) subscribed.
2. In the developer console, set your account's support email and emergency
   contact, and accept the developer terms.
3. Write the listing (`tassyir listing pull`, edit, `tassyir listing push`)
   and upload its images in the developer console.
4. Run the review checks: `tassyir submit --checks-only`.
5. Submit: `tassyir submit --distribution public`.

```bash theme={null}
tassyir listing pull                 # writes tassyir.listing.json
tassyir listing push                 # saves it as the draft, lists what is missing
tassyir submit --checks-only         # the checklist, nothing submitted
tassyir submit --distribution public --note "Demo account: demo@acme.example.com"
tassyir submissions                  # where your reviews stand
```

An agent with the [dev MCP server](https://developers.tassyir.io/packages/dev-mcp)
runs the checks with its `run_review_checks` tool. Submitting stays a
person's decision: the tools never submit for you.

## The listing

The listing belongs to the app, not to a version. You edit a **draft** at any
time; the marketplace shows the **live** listing, which changes only when a
review approves the draft. Write every text in Arabic **and** English.

| Field | Rule |
| - | - |
| `name` | The app's name, at most 30 characters to be listed. Once listed, the app is renamed here, through a review. |
| `tagline` | One line, 10 to 100 characters. |
| `description` | 100 to 1,500 characters of plain text: paragraphs and `- ` lines. |
| `features` | 1 to 6 lines of at most 80 characters. |
| `category` | One of `orders`, `delivery`, `marketing`, `messaging`, `reviews`, `storefront`, `catalog`, `analytics`, `finance`, `customer_service`, `productivity`. |
| `searchTerms` | At most 5 terms of 2 to 30 characters. |
| `iconMediaId` | A square icon, 512 to 1200 px. |
| `screenshots.desktop` | 3 to 6 images, exactly 16:9 (1600x900 to 3200x1800), each with an `alt` of at most 120 characters. |
| `screenshots.mobile` | 0 to 4 images, exactly 9:16 (900x1600 to 1800x3200), each with an `alt`. |
| `supportUrl` | Your support page. |
| `privacyPolicyUrl` | Required. Your privacy policy: what data the app keeps, where, and for how long. |
| `externalService` | When the app needs an account on your own service: `{ name, url, paid }`. The listing then says "Requires an account on \{name}, which may be paid". |
| `languages` | The languages your app's own pages support: `ar`, `en`, `fr`. |

Every text is **plain text**: no HTML, no Markdown link, no invisible or
control characters. Links are `https` addresses on your own public domain
(port 443, no IP address, no Tassyir domain). Images are PNG, JPEG or WebP of
at most 2 MB, uploaded by their bytes in the developer console; the listing
names them by id (`tassyir listing pull` lists them).

`tassyir listing pull` writes the draft as `tassyir.listing.json`:

```json theme={null}
{
  "name": { "ar": "طلبات التقييم", "en": "Review Requests" },
  "tagline": {
    "ar": "اطلب من زبائنك تقييما بعد التسليم",
    "en": "Ask your buyers for a review after delivery"
  },
  "description": {
    "ar": "يرسل التطبيق رسالة إلى كل زبون بعد تسليم طلبه…",
    "en": "Sends each buyer a message once the order is delivered…"
  },
  "features": [{ "ar": "رسالة بعد التسليم", "en": "A message after delivery" }],
  "category": "reviews",
  "searchTerms": ["reviews", "ratings"],
  "iconMediaId": "7400000000000000062",
  "screenshots": {
    "desktop": [
      {
        "mediaId": "7400000000000000063",
        "alt": { "ar": "لوحة التقييمات", "en": "The reviews dashboard" }
      }
    ],
    "mobile": []
  },
  "supportUrl": "https://acme-apps.example.com/support",
  "privacyPolicyUrl": "https://acme-apps.example.com/privacy",
  "externalService": null,
  "languages": ["ar", "en"]
}
```

`tassyir listing push` sends the whole file as the draft (a field left out or
`null` is cleared). It is refused, with every problem at once
(`LISTING_INVALID`), only for what is never right: HTML in a text, a length
over its maximum, an unknown category, an image that is not the app's. What
is still missing (the second language, a screenshot, the privacy policy) is
saved, and listed as `issues`, each with a `fix`. A submission needs none
left.

## The developer terms

A submission needs the current developer terms accepted, in the developer
console. They cover, among other things:

* buyer data stays within what your scopes allow, and is deleted when the
  compliance topics ask;
* no block collects buyer contact data;
* no rating is bought, rewarded or pressured;
* Tassyir may pause an app at once when it harms merchants or buyers.

When Tassyir publishes a new version of the terms, you accept it again before
your next submission (`DEVELOPER_TERMS_REQUIRED`). Apps already listed keep
working.

Your account also needs a support email and an **emergency contact** (an
email and a phone in international form) before a submission. Only you and
Tassyir staff read the emergency contact. In your first review, the reviewer
verifies who you are; the marketplace then shows "Verified developer".

## The review checklist

Every submission runs these checks first, in this order. A **hard** check
that fails stops the submission (`checks_failed`): fix it and submit again. A
warning is for the reviewer.

| Check | What it checks | Hard |
| - | - | - |
| `listing_complete` | Every listing field present and within its rule, in both languages, the images uploaded | yes |
| `privacy_policy_reachable` | `privacyPolicyUrl` answers 200 with an HTML page over https within 5 seconds (at most 3 redirects) | yes |
| `support_contact` | Your account's support email and emergency contact are set | yes |
| `terms_accepted` | The current developer terms are accepted | yes |
| `version_releasable` | The latest version can be released: its manifest validates; on Tassyir Hosting, its scan passed | yes |
| `compliance_topics` | The version subscribes `customers/data_request`, `customers/redact` and `business/redact` | yes |
| `webhooks_verify_signatures` | On your own server: each webhook endpoint answers 2xx to a correctly signed test delivery and 4xx (never 2xx) to a forged signature | yes |
| `admin_page_frames` | On your own server: `admin.page` answers within 3 seconds, may be framed by `https://app.tassyir.io` | yes |
| `blocks_valid` | Every storefront block passes the upload check | yes |
| `api_version_current` | The version names a supported API version | yes |
| `sensitive_scopes` | Names the sensitive scopes the version asks for (`read_customer_contact`, `read_finance`, `read_costs`, `dispatch_orders`, `write_storefront`) | warning |
| `scan_findings` | On Tassyir Hosting: the scan's warnings and the AI review's notes | warning |
| `developer_verified` | Whether you are verified yet; the reviewer verifies you in your first review | warning |

Each result is `{ key, status, hard, message, fix }`, where `status` is
`pass`, `fail`, `warning`, `skipped` (it does not apply, like webhooks for an
app without any) or `error` (Tassyir could not run it; never yours to fix,
and it never stops a submission).

### Webhooks that refuse a forged signature

`webhooks_verify_signatures` sends two deliveries to every webhook endpoint:
a test delivery signed like a real one (marked `tassyir-test: true`), which
must get a 2xx, and one with a forged signature, which must get a 4xx. Verify
every delivery with `@tassyir/app`, answer 2xx to a test delivery, and 400
when verification fails:

```ts theme={null}
import { isTassyirError, TassyirVerificationError } from '@tassyir/app';

// POST /webhooks
export async function receive(request: Request): Promise<Response> {
  try {
    const delivery = await tassyir.verifyWebhook(request, {
      installationId,
      testDeliveries: 'accept',
    });
    if (delivery.test) return new Response(null, { status: 204 });
    // … handle delivery.event, at least once, in any order …
    return new Response(null, { status: 204 });
  } catch (error) {
    if (isTassyirError(error, 'KEYS_UNAVAILABLE')) {
      return new Response(null, { status: 503 });
    }
    if (error instanceof TassyirVerificationError) {
      return new Response(null, { status: 400 });
    }
    throw error;
  }
}
```

An endpoint that answers 2xx to anything, or that skips verification for a
test delivery, fails the check.

### The admin page in a frame

The dashboard shows `admin.page` in a frame from `https://app.tassyir.io`.
Do not send `X-Frame-Options: DENY` or `SAMEORIGIN`, and if you send a
`Content-Security-Policy` with `frame-ancestors`, include
`https://app.tassyir.io`. The check sends no session, so a 401 or 403 is
fine.

### Run the checks first

`tassyir submit --checks-only` runs the whole checklist on your draft listing
and latest version, exactly as a submission would, and submits nothing. It
fetches your privacy policy and admin page and sends the two test deliveries
to your endpoints, so it is limited to **5 runs per app per hour**
(`REVIEW_CHECKS_RATE_LIMITED`, with `retryAfterSeconds`): fix everything one
run names before the next.

## Submitting

`tassyir submit --distribution public` (or `unlisted`) snapshots the draft
listing and names your **latest** version. A `--note` reaches the reviewer:
test steps, a demo account on your service. A new submission replaces a
review still open, and so does any new upload of the app: a reviewer never
decides on something stale.

| State | Meaning |
| - | - |
| `checking` | The checklist is running (seconds to a minute) |
| `checks_failed` | A hard check failed: fix it, then submit again |
| `submitted` | Waiting for a reviewer |
| `in_review` | A reviewer is on it |
| `approved` | The listing is live and the version released |
| `changes_requested` | The reviewer asked for changes, each named: make them and submit again |
| `rejected` | Not listed; your live listing, if any, is unchanged |
| `withdrawn` | You took it back |
| `superseded` | A newer submission or upload replaced it |

Tassyir aims to decide within **5 working days** for a first listing and
**2 working days** for anything after (a resubmission, a listing update, a
new version); working days are Sunday to Thursday. An open review carries
its `turnaround`. You get an email on each decision, and
`tassyir submissions <id>` shows the reviewer's message and notes.

### What a person checks

On top of the checklist, the reviewer installs your app on a dev store and
checks that:

* the app does what the listing says;
* each scope is used, and its reason is honest;
* the listing has no prices, testimonials, superlatives or Tassyir marks;
* the screenshots show the real app;
* storefront blocks look right in Arabic (right to left) and English;
* nothing collects buyer contact data in a block or sends data outside the
  hosts the merchant consented to.

## New versions of a listed app

Once your app is listed, each upload is compared with the last approved
version. Most updates are released by the automated checks alone; a version
goes back to a person only for one of these reasons:

| Reason | When |
| - | - |
| `first_listing` | The app was never listed |
| `scopes_added` | The version asks for a scope the approved one did not (required or optional) |
| `hosts_added` | It reaches a host the merchant has not consented to: the base host, a webhook address, the callback, an allowed host |
| `storefront_code` | A storefront block is added or its template, stylesheet or data changes; an app proxy is added or moved |
| `ai_hold` | On Tassyir Hosting: the AI review of the code asked for a person |

Dropping scopes or hosts, changing webhook topics within your scopes, data
definitions, settings labels or `admin.page`: no person, released once the
checks pass. With a reason, the version waits for review and a review opens
by itself; add notes to it with the developer console, nothing else to
submit. `tassyir submissions` lists it.

An upload of a listed app must still subscribe the compliance topics and name
a supported API version, or it is refused before anything is stored
(`REVIEW_CHECKS_FAILED`). Whatever the review decides, an installation stays
on its version until a member of the business accepts the update, with a
consent screen when it adds scopes or hosts.

## Ratings and reviews

**Not live yet.** Merchants rate the apps they use:

* A business may rate an app it has had installed for at least 48 hours, or
  uninstalled within the last 45 days: 1 to 5 stars and an optional text of
  at most 1,000 characters, once (it can edit or delete its rating). Dev
  stores and your own businesses cannot rate your app.
* A text with a link, an email address or a phone number is refused, and so
  is abusive language. A rating is published at once.
* The merchant chooses to appear by the business's name or as "A Tassyir
  merchant in \{wilaya}".
* The marketplace shows the average and the count, and the stars only from 3
  ratings. A business no longer using the app is marked so.
* You reply once to each rating (and may edit the reply; the latest shows).
  You and merchants can report a rating; Tassyir staff hide what breaks the
  rules.
* Asking for a rating in exchange for anything, or pressuring a merchant, is
  against the developer terms.

## Delisting and pauses

`POST /developer/apps/:appId/delist` takes your listed app out of the
marketplace and search: no new installs, and existing installations keep
working. `relist` brings it back (an app Tassyir delisted only Tassyir
relists).

Tassyir can **pause** an app at once when it harms merchants or buyers (a
leak, a broken app, a policy or legal problem). While paused, its API calls
and webhooks stop, its pages and blocks do not show, and it cannot be
installed; installations and their data are kept, so resuming restores
everything. You get an email with the reason; the merchants are told the
category only.

## Errors

| Code | Fix |
| - | - |
| `DEVELOPER_TERMS_REQUIRED` | Accept the current developer terms in the developer console, then submit again. |
| `LISTING_INVALID` | Fix each error in `errors` (each has a `path` and a `fix`), then push the listing again. |
| `REVIEW_CHECKS_RATE_LIMITED` | Wait `retryAfterSeconds`: 5 runs per app per hour. |
| `REVIEW_CHECKS_FAILED` | A listed app's upload: subscribe the compliance topics and name a supported API version. |
| `REVIEW_CASE_STATE` | The review is closed: submit again (a new review). |
| `APP_NOT_LISTABLE` | `reason` says why: `not_listed`, `already_delisted`, `not_delisted`, `delisted_by_tassyir`. |
| `APP_NAME_LOCKED` | A listed app is renamed through its listing: change `name` there and submit it. |

`tassyir submit` refuses, before sending anything, a draft with missing
fields (`LISTING_INCOMPLETE`); a failed hard check ends it with exit code 1
(`SUBMISSION_CHECKS_FAILED`), each check with its `fix`.


# Scopes and consent
Source: https://developers.tassyir.io/guides/scopes-and-consent

Choose the scopes your app asks for, and understand what a merchant consents to on install and on every new version.

A scope is a right your app asks a merchant for: `read_orders`,
`write_products`, `read_customer_contact`. The merchant sees every scope, with
your reason for it, before installing. Ask for the fewest scopes your app
needs: each one is something a merchant must trust you with, and adding one
later means asking every merchant again.

## The scopes

The "checks" column is the permission the API checks for each route the scope
opens. A refusal names it (`PERMISSION_DENIED`, with `permission` and a `fix`
naming the scope).

| Scope | Gives | Checks | Implies |
| - | - | - | - |
| `read_orders` | Every order of the business, and its tracking | `orders:read`, `orders:read-all`, `ordersTracking:read`, `ordersTracking:read-all` | |
| `write_orders` | Create, edit, confirm, cancel and schedule orders, and comment on them | `orders:create`, `orders:update`, `orders:confirm`, `orders:cancel`, `orders:schedule`, `orders:add-comment` | `read_orders` |
| `dispatch_orders` | Hand orders to a real carrier and print labels (**danger**) | `orders:dispatch`, `orders:generate-labels` | `read_orders` |
| `read_returns` | Returned orders | `orders:read-returns` | |
| `write_returns` | Return orders and process returns | `orders:return-order`, `orders:process-returns` | `read_returns`, `read_orders` |
| `read_products` | Products, variants and collections | `products:read`, `categories:read` | |
| `write_products` | Create and change products and collections, upload images | `products:create`, `products:update`, `products:delete`, `categories:create`, `categories:update`, `categories:delete` | `read_products` |
| `read_inventory` | Stock levels | `inventory:read` | |
| `write_inventory` | Correct stock counts | `inventory:create`, `inventory:update` | `read_inventory` |
| `read_costs` | Buy prices (**sensitive**) | `inventory:view-price` | `read_inventory` |
| `read_customers` | Customers: order counts and delivery record, no contact fields | `customers:read` | `read_orders` |
| `read_customer_contact` | Buyers' names, phones, email, address and order notes, on orders, customers and webhooks (**sensitive**, every read logged) | no permission: a field grant | |
| `read_offers` | The merchant's pricing offers: their rules, dates and number of codes, never a code or a buyer | `offers:read` | |
| `write_offers` | Create, change, publish, pause and archive the offers the app owns, and their codes; read their redemptions | `offers:create`, `offers:update`, `offers:delete` | `read_offers` |
| `read_analytics` | Analytics | `analytics:read` | |
| `read_finance` | Finance (**sensitive**) | `finance:read` | |
| `read_stores` | The business's stores | `stores:read` | |
| `read_delivery` | Delivery agents and delivery prices, never carrier credentials | `delivery-agents:read`, `delivery-fees:read` | |
| `write_storefront` | Storefront blocks: refused until they open | no permission | |

* **Implied scopes come with the scope.** `write_orders` brings
  `read_orders`; `read_customers` brings `read_orders`; `write_offers` brings
  `read_offers`. The install screen
  shows the whole set, implied scopes included, and a token's `scope` lists it.
* **`read_customer_contact` opens nothing alone.** It needs `read_orders`:
  among the required scopes when it is required, among all requested scopes
  when it is optional. Without it, contact fields are left out of every answer
  and webhook (the keys are absent, not `null`). See
  [Customers and contact data](/guides/customers).
* **Some scopes have no API routes yet.** `dispatch_orders`, `read_returns`,
  `write_returns`, `read_analytics` and `read_finance` grant permissions that
  no route of API version `2026-10` uses yet. Do not ask for them before you
  need them.
* **Never grantable to an app:** the team and its roles, the business's
  settings and billing, domains, integrations, WhatsApp, and publishing the
  store.

## What an app may do: scopes, stores, plan

What a call may do is the intersection of:

1. **The installation's scopes**, those the merchant granted (required, plus
   the optional ones they ticked), with the scopes they imply.
2. **For an online token, the person's own permissions.** An online token acts
   for one dashboard user, so it can never do more than that person could
   ([Tokens](/guides/tokens#online-tokens-acting-for-a-person)).
3. **The installation's stores.** The merchant gives an app every store of the
   business or selected ones. A store outside them answers HTTP **460**
   `STORE_SCOPE_FORBIDDEN` when your request names it, and a resource of
   another store reads as `404 NOT_FOUND`.
4. **The merchant's plan.** No plan is needed to install an app or call the
   API, but a plan limit refuses an app as it refuses the merchant, with the
   same code (`PLAN_FEATURE_REQUIRED`, `ORDER_LIMIT_REACHED`,
   `SUBSCRIPTION_REQUIRED`).

## The install screen

When a merchant installs your app, the dashboard shows:

* your app's name, the developer's name, website and support email (set when
  you turn on developer mode), and the host of your pages ("by
  reviews.example.com");
* each required scope, with your reason from `access.scope_reasons`, and the
  scopes it implies; sensitive and danger scopes are marked;
* each optional scope, unticked, with its reason;
* **every host your app's data can reach**: `hosting.url`, any absolute
  webhook `uri` and `auth.callback_url`;
* the stores to give the app: all, or selected ones.

Write each reason for the merchant, in one sentence that says what your app
does with the access ("Send the review request to the buyer's phone").

**Who may install.** A member who may manage the business's apps, and only
with scopes whose permissions that member holds: a member cannot open data to
an app that they cannot see themselves. The owner may grant everything.
`read_customer_contact` needs someone who sees every order.

**Where a custom app installs.** On a business whose owner is the app's
developer (your own businesses and [dev stores](/guides/dev-stores)), and on the
one other business you name for the app in the console. Anywhere else, the
install screen says the app is not available.

After the install, the dashboard opens your page if the app has one
(`admin.page`). A headless app with an `auth.callback_url` receives an install
code there instead ([Tokens](/guides/tokens#headless-apps-the-install-code)).
Your app receives `app/installed` if it subscribes to it.

## New versions and updates

An installation is **pinned** to the version its merchant accepted. When you
upload a new version, each installation is offered an update in the dashboard
(**Apps**, **Installed apps**), and stays where it is until a member accepts
it.

* **No consent screen** when the version asks for nothing new: a plain
  confirm.
* **A consent screen** when it adds a scope the installation would hold, or a
  host your data would reach (a new `hosting.url` included). Scopes it drops
  are listed too, and optional scopes new in this version are offered
  unticked.
* **When the granted scopes change, every token of the installation is
  revoked.** Your app receives `app/scopes_updated` (if subscribed). The next
  page view exchanges a new ID token for a token with the new scopes; a
  headless app receives a new install code at its `auth.callback_url`.
* **When only the version changes**, tokens are kept, and the new version's
  webhook topics and addresses apply from the next delivery.

Changing which optional scopes are granted, on the same version, follows the
same rules.

So a version that adds a scope works only on installations that accepted it.
Read the installation's granted scopes from the token response (`scope`) or
from `app/installed` and `app/scopes_updated`, and keep working within them.

## Uninstall

A merchant can uninstall your app at any time. Every token is revoked at
once, and your app receives `app/uninstalled` (if subscribed). The data it
kept in Tassyir is deleted 48 hours later. See
[Compliance and uninstall](/guides/compliance-and-uninstall).


# Stock
Source: https://developers.tassyir.io/guides/stock

Read the stock of the merchant's products, follow it with webhooks, and correct a count with a reason.

An app reads how many units of each variant the business holds (to sync
another channel, or warn before a product runs out) and corrects a count the
way a team member does on the dashboard's Stock page.

| Route | Does | Scope |
| - | - | - |
| `GET /inventory-levels` | List stock items | `read_inventory` |
| `GET /inventory-levels/{id}` | Read one stock item | `read_inventory` |
| `POST /inventory-levels/{id}/adjust` | Correct a count | `write_inventory` |
| the unit cost in any answer | | `read_costs` |

Stock needs the merchant's plan to include it: a business with no usable
subscription answers 422 `SUBSCRIPTION_REQUIRED`, as the dashboard does.

## The stock item

One item is the stock of one variant across the business, with its levels at
each location:

```json theme={null}
{
  "inventoryItemId": "741000000000000800",
  "variantId": "741000000000000501",
  "productId": "741000000000000500",
  "onHand": 12,
  "inTransit": 3,
  "damaged": 1,
  "low": false,
  "lowStockThreshold": 5,
  "locations": [
    {
      "locationId": "741000000000000901",
      "onHand": 8,
      "inTransit": 2,
      "damaged": 1
    },
    {
      "locationId": "741000000000000902",
      "onHand": 4,
      "inTransit": 1,
      "damaged": 0
    }
  ],
  "updatedAt": "2026-10-11T11:00:00.000Z",
  "currency": "DZD",
  "unitCost": "1234.50"
}
```

* Its id is `inventoryItemId` (there is no `id` field); `fields` always keeps
  it.
* `onHand` is the sellable units of every location. **It can be negative**
  after a dispatch shortfall (the business shipped more than it held), and is
  shown as it is. "Available" (on hand minus what confirmed orders will take)
  is not stored, so it is not here.
* `inTransit` and `damaged` are the item's other buckets; `low` is its
  low-stock flag, and `lowStockThreshold` the threshold the merchant set.
* `currency` and `unitCost` (the average cost of the units on hand, a decimal
  string, `null` when unknown) are present **only with `read_costs`**. Webhook
  bodies never carry them.
* Packs have no stock of their own, and packaging stock is not here.

## List and follow

`GET /inventory-levels` lists the items of every product your installation
may read, active or not, newest item first. Filters: `productId` (its
variants' items) and `storeId`.

There is no "changed since" filter: an item's levels can move without the
item changing (a transfer between locations). Subscribe to
`inventory_levels/updated` instead. It is sent once per item per change, with
`changed` empty: the body is the item's whole stock, so replace what you hold
with it.

```ts theme={null}
for await (const item of admin.paginate('/inventory-levels', {
  query: { productId: '741000000000000500' },
})) {
  console.log(item.variantId, item.onHand, item.low ? '(low)' : '');
}
```

## Correct a count

`POST /inventory-levels/{id}/adjust` is the dashboard's **Adjust**: it moves
units and records why. It never records a purchase, a cost or a payment.

```ts theme={null}
const { data: item } = await admin.post('/inventory-levels/{id}/adjust', {
  path: { id: '741000000000000800' },
  body: { delta: -2, reason: 'damaged', note: 'Torn in the warehouse' },
  idempotencyKey: 'count-2026-10-11-RK-01-M',
});
console.log(item.onHand, item.damaged);
```

| Field | Rule |
| - | - |
| `delta` | Required. A whole number of units, not 0, from -1,000,000 to 1,000,000. Positive adds, negative removes. |
| `reason` | Required. `received`, `correction`, `counted`, `damaged`, `theft_or_loss` or `promotion`. `damaged` must be negative: it moves units from on hand to damaged. |
| `note` | Optional, up to 500 characters, kept with the stock history. |
| `locationId` | Optional. The location to correct; the default location when absent. Needs a plan with full inventory: 403 `PLAN_FEATURE_REQUIRED` otherwise. |

* A count never goes below zero here: 409 `INSUFFICIENT_AT_LOCATION`, with
  the figures.
* A pack is 400 (it has no stock of its own); an unknown or inactive location
  is `LOCATION_NOT_FOUND`.
* **Send an `Idempotency-Key`**: a retry then answers the stored result and
  never moves the stock twice.
* The answer is the item read again. The adjustment is recorded in the stock
  history and the activity log under your app's name, and sends
  `inventory_levels/updated`, which your app hears like any other.

Receiving stock at a cost, transfers between locations, the low-stock
threshold, starting or stopping tracking, and the list of locations are not
in API version `2026-10`.


# Storefront blocks
Source: https://developers.tassyir.io/guides/storefront-blocks

Not live yet. Add HTML to a merchant's store pages with a block, a Liquid template Tassyir checks at upload and renders with no JavaScript.

**Not live yet.** Storefront blocks open with the Tassyir app marketplace.
Until then the API refuses `[[storefront.blocks]]` in a manifest. The block
language is published now, in
[`@tassyir/storefront-blocks`](https://developers.tassyir.io/packages/storefront-blocks),
so you can write and test blocks before the opening. This guide describes it;
details may still change until the opening.

A block is a piece of a store page your app provides: a rating under the
product's price, a size chart, a trust badge, a delivery estimate. The
merchant places it in the store builder, like any section. Your app ships the
block's template and stylesheet with its version. Tassyir checks them at
upload, then renders the template on its own servers for every page view,
with the data your app stored.

A block runs no JavaScript and has no form. The store page holds the order
form, with the buyer's name, phone and address, so a block can only ever be
markup and styles: Tassyir escapes every value, rebuilds the HTML from an
allowlist, and scopes the stylesheet to the block.

## Declare a block

In `tassyir.app.toml`, with the `write_storefront` scope:

```toml theme={null}
[[data.definitions]]
owner      = "product"
key        = "rating"
type       = "json"
visibility = "storefront"

[[storefront.blocks]]
handle     = "product-rating"
template   = "blocks/product-rating.liquid"
stylesheet = "blocks/product-rating.css"
name       = { ar = "تقييم المنتج", en = "Product rating" }
target     = "product"
data       = ["product.rating"]

  [[storefront.blocks.settings]]
  key     = "accent_color"
  type    = "color"
  label   = { ar = "اللون", en = "Colour" }
  default = "#0b6e4f"
```

* `target`: `product` for the product page (the template reads `product`),
  or `any` (the default) for any page but checkout.
* `data`: the [app data](/guides/app-data) keys the block reads, as
  `<owner>.<key>`. Each must be declared with `storefront` visibility. Owners:
  `product` (target `product` only), `store`, `business`. Order and customer
  data never reach a store page.
* `settings`: what the merchant sets in the builder. Types: `string`,
  `text`, `boolean`, `integer`, `number`, `select`, `color`, `image`, `url`,
  `product`, `collection`. A value that no longer fits the declaration falls
  back to the default when the block renders.

## The template

A block template is a `.liquid` file in a subset of Liquid. If you know
Shopify's Liquid, the syntax is the same: `{{ value | filter: argument }}`
outputs, `{% tag %}` logic, `{{-` and `-}}` to trim whitespace.

```liquid theme={null}
<section class="rating">
  {%- assign rating = app.data.product.rating -%}
  {%- if rating %}
  <p>{{ rating.average | stars }} <small>({{ rating.count }})</small></p>
  {%- else %}
  <p>{{ product.name }}: no reviews yet</p>
  {%- endif %}
  <img src="{{ product.image | image_url: 320 }}" alt="{{ product.name }}">
</section>
```

### Objects

| Object | What it holds |
| - | - |
| `block.settings.<key>` | The merchant's value of each setting. |
| `product` | Target `product` only: `id`, `name`, `url`, `price` and `compareAtPrice` (decimal strings, `compareAtPrice` may be nil), `currency`, `image`, `available`. |
| `store` | `name`, `url`, `locale` (`ar`, `fr`, `en`), `direction` (`rtl`, `ltr`), `currency`. |
| `app.data.<owner>.<key>` | Your app data the block lists in `data`: owner `product`, `store` or `business`. A key with no value is nil. |
| `forloop` | Inside a `for` loop: `index`, `index0`, `rindex`, `rindex0`, `first`, `last`, `length`. |

Nothing about the buyer or the cart is ever available. Any value answers
`size`, `first` and `last`; a record answers its own keys only. A name that is
not one of these objects or a variable the template assigns is an error at
upload.

### Tags

| Tag | Notes |
| - | - |
| `if` / `elsif` / `else` / `endif`, `unless` | Operators `==`, `!=`, `<>`, `<`, `>`, `<=`, `>=`, `contains`; `and` / `or` read from the right. `empty` and `blank`. |
| `case` / `when` / `else` / `endcase` | `when` takes several values: `when 'a', 'b'` or `when 'a' or 'b'`. |
| `for` / `else` / `endfor`, `break`, `continue` | `limit:`, `offset:`, `reversed`. A loop runs at most 50 times; a range may use variables. |
| `assign`, `capture` / `endcapture` | Variables live for the whole template; a loop's variable only inside its loop. |
| `comment` / `endcomment`, `{% # note %}` | Removed from the output. |

Not available, each refused at upload with a fix: `include`, `render`,
`section`, `layout`, `block`, `raw`, `liquid`, `echo`, `form`, `schema`,
`style`, `stylesheet`, `javascript`, `paginate`, `tablerow`, `cycle`,
`increment`, `decrement`. A block is one self-contained template.

### Filters

| Filters | Notes |
| - | - |
| `append`, `prepend`, `capitalize`, `downcase`, `upcase`, `strip`, `lstrip`, `rstrip`, `strip_newlines`, `strip_html`, `replace`, `replace_first`, `replace_last`, `remove`, `remove_first`, `remove_last` | Text. |
| `truncate`, `truncatewords`, `slice`, `split`, `url_encode`, `default` | Lengths count characters, not bytes. |
| `size`, `first`, `last`, `join`, `reverse`, `sort`, `sort_natural`, `map`, `where`, `uniq`, `compact`, `concat`, `sum` | Lists. `sort` orders by character code, the same everywhere. |
| `plus`, `minus`, `times`, `divided_by`, `modulo`, `abs`, `ceil`, `floor`, `round`, `at_least`, `at_most` | Numbers have one type: `7.0` is `7`. `divided_by: 0` and `modulo: 0` give nil. |
| `escape`, `escape_once` | Accepted, and change nothing: every output is already escaped. |
| `money` | The storefront's price format: `4 500 دج` in Arabic, `4 500 DA` in French and English. |
| `image_url: <width>` | A Tassyir image at that width (80, 160, 240, 320, 480, 640, 800, 1080 or 1600, rounded up). Anything else gives an empty string. |
| `stars` or `stars: <max>` | A rating as stars with an accessible name in the store's language. Use it between tags. |
| `t` | Picks the store's language from `{ ar, fr, en }` (a text setting can hold one per language). |

Not available, each refused with a fix: `raw` (there is no unescaped output),
`date` (a block has no clock: store the date as text), `json`, `img_url` (use
`image_url`), `money_with_currency` (use `money`), `link_to`, `script_tag`,
`stylesheet_tag`, hashes and base64.

## The HTML a block may use

The rendered HTML is parsed and written out again from an allowlist. What the
template writes outside the allowlist is an error at upload; what data brings
in is removed at render.

* **Elements:** `a`, `abbr`, `article`, `aside`, `b`, `bdi`, `bdo`,
  `blockquote`, `br`, `caption`, `cite`, `code`, `dd`, `del`, `details`,
  `dfn`, `div`, `dl`, `dt`, `em`, `figcaption`, `figure`, `footer`, `h2` to
  `h6`, `header`, `hr`, `i`, `img`, `ins`, `kbd`, `li`, `mark`, `meter`, `ol`,
  `p`, `pre`, `progress`, `q`, `s`, `samp`, `section`, `small`, `span`,
  `strong`, `sub`, `summary`, `sup`, the table elements, `time`, `u`, `ul`,
  `var`, `wbr`. No `h1`: the page has its own.
* **SVG icons:** `svg` with `g`, `path`, `circle`, `ellipse`, `line`,
  `polygon`, `polyline`, `rect` and a text-only `title` inside it, with their
  shape and paint attributes (`fill="currentColor"` follows the text colour).
* **Attributes:** `class`, `title`, `lang`, `dir`, `role`, `hidden`,
  `translate`, a set of `aria-*`, and each element's own (`href` and `target`
  on links; `src`, `alt`, `width`, `height` on images; `colspan`, `datetime`,
  `open`, …). No `id` or `name`: an element with an id becomes a global
  variable of the page, which can break the store's own scripts. No `style`
  (use the stylesheet), no `data-*`, no `on…` handler.
* **Links:** `https://` addresses (Tassyir adds `rel="nofollow noopener
  noreferrer"`), paths on the store (`/collections/all`) and fragments.
* **Images:** an `<img>` takes its `src` from `{{ … | image_url: <width> }}`
  only, so every image comes from Tassyir's CDN. Images load lazily.
* **Text:** bidirectional override and isolate characters, zero-width and
  control characters are removed from values; Arabic's marks and joiners stay.

Liquid may fill a quoted attribute value or an element's content. It may not
make an element or attribute name (`<{{ x }}>`), nor fill an unquoted value.

## The stylesheet

The optional `.css` file is scoped to the block's section, so its selectors
cannot reach the rest of the page, and the block is drawn inside its section's
box. At upload it is refused when it holds:

* an at-rule other than `@media`, `@supports` and `@keyframes <plain name>`
  (no `@import`, `@font-face`, `@layer`), or a nested rule;
* a `url()` outside `https://cdn.tassyir.io/`, or a function that loads
  something (`image-set()`, `src()`);
* `position` other than `static`, `relative`, `absolute` or `sticky`,
  written as the word itself (never `fixed`, never through `var()`);
  `behavior`, `-moz-binding`, `expression()`;
* a backslash escape outside a quoted string, `<`, a bidi or invisible
  character.

Match the store's theme with its variables:

| Variable | What it is |
| - | - |
| `--st-primary`, `--st-on-primary` | The brand colour, and text on it. |
| `--st-primary-text` | The brand colour as text on the page background. |
| `--st-secondary` | The second brand colour. |
| `--st-bg`, `--st-surface` | The page background, and cards and panels. |
| `--st-text`, `--st-muted` | The main and the secondary text colour. |
| `--st-border` | Borders and dividers. |
| `--st-font`, `--st-heading-font` | The body and the heading font family. |
| `--st-heading-weight`, `--st-body-size` | The heading weight and the body font size. |
| `--st-radius`, `--st-space`, `--st-shadow` | Corner radius, spacing unit, card shadow. |

Other `--st-*` variables may change without notice and are refused. Each
`color` setting is published on the block as `--block-<key>`, underscores as
hyphens: `accent_color` is `var(--block-accent-color)`.

```css theme={null}
.rating {
  color: var(--block-accent-color);
  background: var(--st-surface);
  border-radius: var(--st-radius);
  padding: var(--st-space);
}
.rating small {
  color: var(--st-muted);
}
```

## Limits

A template is at most 16 KB, a stylesheet 8 KB, a version at most 20 blocks
and 100 KB of block files. A render reads at most 32 KB of app data and writes
at most 32 KB of HTML. A `for` loop runs at most 50 times, and at most 3 loops
nest. Render work is counted in steps, never timed: every tag, output, loop
iteration and condition is a step, and every filter or comparison costs one
more per 256 characters it touches, up to 20,000 steps. A block over a limit
renders nothing: the page shows without it.

## Test a block on your machine

The `tassyir` CLI reads your manifest's blocks and runs the upload check on
their files, offline, every problem with its file, line and column:

```bash theme={null}
tassyir validate                     # the manifest, then every block's files
tassyir block preview product-rating --lang en --data data.json
tassyir block preview product-rating --out preview.html   # a page to open in a browser
```

`block preview` renders one block with sample data (the store "Dar Amina", a
product for target `product`, each setting at its default), plus the
settings values (`--settings`) and app data (`--data`, by owner:
`{ "product": { "rating": … } }`) you pass. It prints the HTML the store
would show; `--out` writes a page with your stylesheet, where no script can
run. Agents use the dev MCP server's `validate_block` tool for the same check.

`tassyir deploy` checks the blocks again and uploads their files with the
version: an app on Tassyir Hosting carries them in its bundle, at the paths
the manifest names; an app on your own server sends them next to the
manifest. Every block file of a version weighs 100 KB at most together.

The package runs the same check and renders previews in your own code: the
store "Dar Amina", a product with a price, your settings' defaults, and the
app data you pass.

```ts theme={null}
import {
  renderBlock,
  sampleBlockContext,
  validateBlock,
} from '@tassyir/storefront-blocks';
import type { BlockDeclaration } from '@tassyir/storefront-blocks';
import { readFileSync } from 'node:fs';

const declaration: BlockDeclaration = {
  target: 'product',
  settings: [{ key: 'accent_color', type: 'color', default: '#0b6e4f' }],
  data: ['product.rating'],
};
const template = readFileSync('blocks/product-rating.liquid', 'utf8');
const stylesheet = readFileSync('blocks/product-rating.css', 'utf8');

const check = validateBlock({ template, stylesheet, declaration });
if (!check.ok) {
  for (const error of check.errors) {
    console.error(
      `${error.source}:${String(error.line)}:${String(error.column)} ${error.code}: ${error.message} ${error.fix}`,
    );
  }
}

for (const language of ['ar', 'fr', 'en'] as const) {
  const preview = renderBlock(
    template,
    sampleBlockContext(declaration, {
      language,
      appData: { product: { rating: { average: 4.4, count: 128 } } },
    }),
    declaration,
  );
  console.log(language, preview.ok ? preview.html : preview.errors);
}
```

`validateBlock` is the check the API runs on upload: it compiles the template
against the declaration, checks the stylesheet, and renders the block with
sample data in Arabic, French and English and with no app data, since a
block must render before your app has stored anything.

## Errors

Every error has a stable `code`, a `source` (`template`, `stylesheet` or
`render`), a 1-based `line` and `column` (0 for a render limit), a `message`
and a `fix`. On upload, the API refuses a version with an invalid block with
`BLOCK_TEMPLATE_INVALID`, naming the block and listing these errors. The
package's reference lists
[every code](https://developers.tassyir.io/packages/storefront-blocks#what-you-get-back).
The ones you will meet first:

| Code | Fix |
| - | - |
| `BLOCK_VARIABLE_UNKNOWN` | Read `block`, `product`, `store`, `app`, or a variable the template assigns. |
| `BLOCK_DATA_KEY_UNDECLARED` | List the key in the block's `data`, declared with `storefront` visibility. |
| `BLOCK_OBJECT_NOT_AVAILABLE` | Set `target = "product"` to read the product. |
| `BLOCK_HTML_TAG_NOT_ALLOWED` | Use an allowed element: no script, style, form, frame or `h1`. |
| `BLOCK_HTML_IMAGE_SOURCE` | Write `src="{{ image \| image_url: 320 }}"`. |
| `BLOCK_HTML_STYLE_ATTRIBUTE` | Move the styles to the stylesheet. |
| `BLOCK_TAG_NOT_SUPPORTED` | Put the markup in the template itself. |
| `BLOCK_RENDER_STEP_LIMIT` | Do less work: fewer iterations, fewer filters on long strings. |


# Stores and delivery
Source: https://developers.tassyir.io/guides/stores-and-delivery

Read a business's stores, the carriers it ships with and what it charges buyers for delivery to each wilaya.

A business has one or more stores (storefronts), and orders, products and
stock each carry a `storeId`. It ships through delivery agents (carrier
accounts or its own couriers) at the delivery prices it sets per wilaya. An
app reads all of these to name a store, quote a delivery price, or follow a
parcel. None of these routes writes, and no route ever reaches a carrier.

| Route | Scope |
| - | - |
| `GET /stores`, `GET /stores/{id}` | `read_stores` |
| `GET /delivery-agents`, `GET /delivery-agents/{id}` | `read_delivery` |
| `GET /delivery-fee-groups`, `GET /delivery-fee-groups/{id}` | `read_delivery` |

## Stores

```json theme={null}
{
  "id": "741000000000000100",
  "name": "Dar Amina",
  "description": "Handmade in Tlemcen",
  "logo": "https://cdn.tassyir.io/images/aa11/public",
  "status": "active",
  "language": "ar",
  "subdomain": "dar-amina",
  "delivery": {
    "feeGroupId": "741000000000003000",
    "deliveryAgentId": "741000000000004000",
    "speeds": "both",
    "defaultSpeed": "standard"
  },
  "createdAt": "2026-01-02T03:04:05.000Z",
  "updatedAt": "2026-10-11T09:12:44.120Z"
}
```

* `language` is the storefront's language as the merchant chose it, or
  `null` when they never chose.
* `subdomain` is the store's address on Tassyir's storefront domain. Custom
  domains are not here yet.
* `delivery.feeGroupId` is the delivery fee group that prices this store's
  checkout; `delivery.deliveryAgentId` the store's default carrier; `speeds`
  is `standard`, `economy` or `both`.
* An installation limited to selected stores lists only those; another store
  named by id is 460 `STORE_SCOPE_FORBIDDEN`.
* A store's ad and conversion-tracking settings and tokens are never sent.

## Delivery agents

An agent is one carrier account of the business, or a private courier (a
team member who delivers).

```json theme={null}
{
  "id": "741000000000004000",
  "carrier": "Yalidine",
  "name": "Yalidine",
  "label": "Main account",
  "image": "https://cdn.tassyir.io/images/yalidine/public",
  "privateCourier": false,
  "status": "active",
  "deletedAt": null,
  "createdAt": "2026-03-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z"
}
```

* `name` is what the dashboard shows: the carrier, or a private courier's
  label or name. `image` is the carrier's logo.
* `deletedAt` is set once the merchant removed the agent. The list leaves
  removed agents out, but `GET /delivery-agents/{id}` still reads one, since
  orders keep naming it (`delivery.deliveryAgentId`).
* Agents have no store: every installation reads the business's agents.
* **Carrier credentials never leave Tassyir**: no route answers an account's
  keys, tokens, secrets, balance or settings.

## Delivery fee groups

A fee group is what the business charges a buyer for delivery, per wilaya and
method. A store prices its checkout with one group.

```json theme={null}
{
  "id": "741000000000003000",
  "name": "Yalidine prices",
  "storeId": "741000000000000100",
  "deliveryAgentId": "741000000000004000",
  "isDefault": true,
  "chargeOverweight": false,
  "currency": "DZD",
  "fees": [
    {
      "provinceCode": 16,
      "deliverable": true,
      "stopdeskAvailable": true,
      "homeFee": "500.00",
      "stopdeskFee": "350.00",
      "economyHomeFee": null,
      "economyStopdeskFee": null
    }
  ]
}
```

* **`id` is opaque**: digits for most groups, a name-like string for older
  ones.
* `storeId` is `null` for a business-wide group. `deliveryAgentId` names the
  carrier whose prices it holds, if any. `chargeOverweight` adds the carrier's
  overweight surcharge to the buyer's price.
* `fees` has one entry per wilaya (`provinceCode` 1 to 58): the standard
  speed's `homeFee` and `stopdeskFee`, and the economy speed's (`null` when
  not offered), as decimal strings.
* `GET /delivery-fee-groups` lists every active group **without `fees`**, and
  is **not paged** (`{ "data": [...] }`, a business holds a handful). Read one
  group for its fees. Filter with `storeId` (that store's groups only, the
  business-wide ones left out).
* An installation limited to selected stores reads its stores' groups and the
  business-wide ones.

```ts theme={null}
// The home-delivery price of a store's checkout for one wilaya.
export async function homeFee(storeId: string, provinceCode: number) {
  const { data: store } = await admin.get('/stores/{id}', {
    path: { id: storeId },
  });
  const groupId = store.delivery.feeGroupId;
  if (groupId === null) return null;
  const { data: group } = await admin.get('/delivery-fee-groups/{id}', {
    path: { id: groupId },
  });
  const fee = group.fees?.find((entry) => entry.provinceCode === provinceCode);
  return fee?.deliverable
    ? { amount: fee.homeFee, currency: group.currency }
    : null;
}
```


# Tassyir Hosting
Source: https://developers.tassyir.io/guides/tassyir-hosting

Run your app on Tassyir with no server of your own, from the hosted template to tassyir deploy, the scan's findings and what each request receives.

On Tassyir Hosting your app's code runs on Tassyir, on Cloudflare Workers:
there is no server for you to run. It is the same app as one on your own
server: the same manifest, scopes, consent, Admin API, webhooks and App
Bridge. Only where the code runs changes, and an app may move between the
two from one version to the next.

**Tassyir Hosting is not open yet.** Until it opens, the API refuses a hosted
version with `APP_HOSTING_NOT_AVAILABLE` and `tassyir deploy` says so; run
your app on your own server meanwhile (`hosting.mode = "external"`). This
guide is the contract hosting opens with, so you can build for it now.

## Start from the template

The `hosted` template of `create-tassyir-app` starts a project that deploys
as it is:

```bash theme={null}
npm create tassyir-app@latest -- --template hosted
```

(`tassyir app init --template hosted` writes the same project.) It holds a
Worker (Hono) that reads everything from `ctx.props`, a React page on
`@tassyir/app-bridge/react` and `@tassyir/ui`, webhooks checked with
`verifyHostedWebhook`, an example of `STORAGE` and of an Admin API read, and
specs that run the Worker in workerd with stand-in `ctx.props`. It holds no
secret and no `.env`. In the new folder:

| Command | What it does |
| - | - |
| `npm run check` | Validates the manifest, typechecks, runs the specs, then `deploy:check` |
| `npm run deploy:check` | Builds the page, then `tassyir deploy --dry-run`: the bundle built and checked, with no sign-in and nothing sent |
| `npm run deploy` | Builds the page, then `tassyir deploy` |

Then sign in (`npx tassyir login`: the CLI is a dev dependency of the
project), create the app once (`npx tassyir app create`: its handle is
permanent), deploy it (`npm run deploy`), and make a
[dev store](/guides/dev-stores) to install it on (`npx tassyir store create`).

## What a hosted app is

A hosted app sets `hosting.mode = "tassyir"` and lists every host its code
calls in `allowed_hosts` (an empty list when it calls none):

```toml theme={null}
name        = "Review Requests"
handle      = "review-requests"
api_version = "2026-10"

[access]
scopes = ["read_orders"]

[access.scope_reasons]
read_orders = "Find delivered orders to ask for a review"

[hosting]
mode          = "tassyir"
allowed_hosts = ["graph.facebook.com"]

[admin]
page = "/"

[[webhooks]]
topics = ["orders/delivered", "app/uninstalled"]
uri    = "/webhooks"
```

* **Its address is `https://{handle}.tassyir-apps.com`**, and `admin.page` and
  each webhook `uri` are paths on it. A hosted app has no `hosting.url`, no
  `auth.callback_url` and no absolute webhook `uri`.
* **It answers only inside the dashboard.** The dashboard opens your page in
  its frame with a session it started for that member and that installation.
  A visit to the address in a browser tab, a frame on another site, or a
  request from another app gets a short refusal, never your page.
* **`/.tassyir/` is Tassyir's.** On a hosted app's origin, `/.tassyir` and
  every path below it are answered by Tassyir itself (that is where the
  dashboard's session starts). The manifest refuses `admin.page` or a webhook
  `uri` there (`MANIFEST_PATH_RESERVED`), and a link of yours to it leads
  nowhere.
* **Each installation runs the version its merchant accepted**, the same as
  for an app on your server: a new version is offered to each installation
  as an update ([Scopes and consent](/guides/scopes-and-consent#new-versions-and-updates)).
  Only a version that passed its scan and was released runs, on a merchant's
  business and on a [dev store](/guides/dev-stores) alike.

## The code

The code is one ES module whose default export has a `fetch` handler, the
Workers way. Everything about the installation arrives in `ctx.props`, per
request; `env` is empty. `readHostedProps(ctx)` from `@tassyir/app` returns
it typed (`HostedProps`) after checking its shape, and throws
`HOSTED_PROPS_MISSING` (a `TassyirError` with a `fix`) anywhere else: code
run outside Tassyir Hosting, or a test that forgot its stand-in props.

```ts theme={null}
import { hostedAdmin, readHostedProps } from '@tassyir/app';

export default {
  async fetch(
    request: Request,
    env: unknown,
    ctx: { props?: unknown },
  ): Promise<Response> {
    const props = readHostedProps(ctx);
    if (new URL(request.url).pathname !== '/') {
      return new Response('Not found', { status: 404 });
    }
    const { data: orders } = await hostedAdmin(props).get('/orders', {
      query: { limit: 5 },
    });
    return new Response(
      `${props.installation.handle}: ${String(orders.length)} recent orders`,
    );
  },
};
```

| `ctx.props` | What it is |
| - | - |
| `installation` | The installation this request is for: its `id`, `businessId`, `appId`, `handle`, the `version` it runs, the `scopes` granted, its store access (`storeAccess`, `storeIds`) and `devStore`. |
| `viewer` | Who is looking: `userId` and `sessionId` of the dashboard member whose frame made the request, or `null` (a webhook). It says who is looking, not what they may do: the dashboard let them open the app, and what your page shows them is your app's decision. A hosted page needs no ID token: the viewer is already verified. |
| `STORAGE` | The installation's own SQLite database ([below](#storage)). |
| `TASSYIR` | The Admin API, called as the installation, with no token ([below](#call-the-admin-api)). |

`STORAGE` and `TASSYIR` are capabilities: they act for this request's
installation, and your code can neither read nor change which one.

**Keep per-request state per request.** One copy of your code serves every
installation that runs the same version, possibly several merchants in one
process: a variable at the top of a module is shared between them. Never
cache a merchant's data in one; use `STORAGE` or the request.

**Change things only on a write.** Never change state on a `GET`: change it
on `POST`, `PUT`, `PATCH` or `DELETE` from your own page, which are refused
from anywhere else. Your page's requests never carry the dashboard's session,
and a cookie your app sets stays on your app's host. Do not use your own
cookies as a CSRF defence (a double-submit cookie): another app's page may be
able to set a cookie for the whole `tassyir-apps.com` domain.

**Limits per request:** 300 ms of CPU and 50 subrequests (each `fetch`, each
call to `STORAGE` or `TASSYIR`). Past either, the request fails, and the
merchant's frame shows an error.

**In tests**, pass stand-in props of the same shape: the template's specs run
the Worker in workerd with a real SQLite database as `STORAGE` and a fake
Admin API as `TASSYIR`.

## The page

`admin.page` is a path your Worker serves like any other, inside the
dashboard's frame, and the page is an [embedded page](/guides/embedded-pages) like
an external app's: App Bridge drives the title bar, the save bar, toasts,
modals and pickers. In React, use the entry point
[`@tassyir/app-bridge/react`](https://github.com/tassyir/apps-sdk/tree/main/packages/app-bridge#react):
`AppBridgeProvider` holds the page's bridge, and the hooks call it from your
components (`useBridgeContext`, `useTitleBar`, `useSaveBar`, `useToast`,
`useModal`, `useResourcePicker`, `useNavigate`).

The page needs no token and no ID token: it calls its own Worker on the same
origin, and the Worker knows who is looking from `ctx.props.viewer` and calls
the Admin API with `hostedAdmin`. Refuse a page's API request whose `viewer`
is `null`: only a webhook delivery runs without one. The template's page
works this way: it lists the pending orders its Worker reads with
`hostedAdmin`, and edits settings its Worker keeps in `STORAGE`, with the
save bar.

## Deploy with the CLI

[`tassyir deploy`](https://github.com/tassyir/apps-sdk/tree/main/packages/cli#tassyir-hosting)
does everything in one command, in the folder that holds
`tassyir.app.toml`:

```bash theme={null}
tassyir deploy
```

1. **Build.** It bundles your Worker's entry (`--entry <file>`, else the
   first of `src/worker.ts`, `src/worker.js`, `src/index.ts`, `src/index.js`)
   into one ES module, `worker.js`. `.html` and `.css` files import as text
   (`import page from './page.html'` is a string).
2. **Check, before anything is sent.** The bundle rules below and the scan's
   checks that need nothing of Tassyir's: every problem at once, each at its
   place in your source (`src/worker.ts:12`), exit code 4. Nothing is
   uploaded until they pass.
3. **Upload** the manifest and the bundle, with your lockfile
   (`package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`
   or `bun.lock`), which is scanned and never deployed.
4. **Follow the scan** until the version is released or refused, then exit
   by the verdict.

To run steps 1 and 2 only, before you sign in or while you change the code:

```bash theme={null}
tassyir deploy --dry-run
```

It builds and checks exactly as `deploy` does, signs in to nothing and sends
nothing: exit 0 when `deploy` would upload the bundle, 4 when it would refuse
it (`BUNDLE_INVALID` or `BUNDLE_BUILD_FAILED`, each problem at its place in
your source). With `--json` it prints one document with `"dryRun": true`,
the `entry`, `main`, `bytes`, `lockfile` and `warnings`. The template's
`npm run deploy:check` is the page's build, then this.

With `--json`, `deploy` prints one line when the version is uploaded (its
number, and the command to follow it) and one with the verdict, so a tool
whose own call times out still knows which version to check:

```bash theme={null}
tassyir app version 3 --follow --app review-requests
```

`tassyir app version [n]` shows a version (the latest by default) with its
scan; `--follow` waits for the verdict and exits as `deploy` does.

### The bundle rules

| Rule | Limit |
| - | - |
| Files | 1 to 100, at most 3 MB of UTF-8 together. Text only: ES modules (`.js`, `.mjs`) and text (`.html`, `.css`, `.txt`, `.json`, `.svg`, `.liquid`). No WebAssembly, source map or binary file. |
| Paths | At most 200 characters, in at most 9 folders (`a/b/c.js` is in 2); names of letters, digits, `.`, `_` and `-` that never start with `.`. |
| The entry (`main`) | An ES module whose default export holds a `fetch` handler: `export default { async fetch(request, env, ctx) { … } }`, a class with one, or an object that has one (a Hono app). |
| Node.js built-ins | None: a hosted app has no Node.js compatibility, so an import of `node:buffer`, `node:crypto`, … is refused. Use the Web APIs (`fetch`, `crypto.subtle`, `TextEncoder`, `URL`, …) or a package that does not import `node:`. |
| Other imports | Only what the bundle holds, and `cloudflare:workers`. No import of a URL or of `cloudflare:sockets`, and no `import()` of a name built at run time. |
| Lockfile | Optional and recommended, at most 1 MB. Without one, the scan warns that the dependencies were not checked. |
| Uploads | 10 hosted versions per developer a day (each is a scan), 30 versions an hour. |

The same manifest and bundle as the latest version are not a new version:
`deploy` answers with that version's state instead.

## The scan

Every hosted version is scanned before it can run, outside Tassyir's servers.
Each check passes, warns (the version still goes ahead) or fails (it does
not):

| Check | What fails the version |
| - | - |
| `size` | Over 3 MB of modules or 100 files. |
| `unicode` | A bidi control character (Trojan Source), a tag character, a long run of invisible characters, or an invisible character inside a name. |
| `banned_apis` | `eval`, `new Function` or a string timer over code built at run time, `.constructor.constructor()`, `import()` of a run-time name or a URL, `cloudflare:sockets`, an import not in the bundle, a `node:` import, an entry with no `fetch` handler, a module that does not parse. |
| `manifest_scopes` | A call to an Admin API route that none of the manifest's scopes reach. |
| `manifest_hosts` | A `fetch`, `Request`, `WebSocket` or `EventSource` to a literal host outside `allowed_hosts`, to a Tassyir domain, or over http. |
| `semgrep` | Code matching Tassyir's own rules: mining, a Tassyir credential in code, raw sockets. |
| `gitleaks` | A secret in the code. |
| `osv` | A malicious or critical (CVSS 9 or more) package in the lockfile. |

An AI review then reads the code against the manifest. It can only add
caution: it fails a version, or holds it for a person at Tassyir, but it
never passes a version a check failed.

Each finding names its `rule`, `severity` (`error` fails, `warning` does not),
`file`, `line` and a `message`. The checks read the code and never run it:
a host or a path built at run time is left to the limits at run time
([egress](#call-other-services), the installation's scopes).

| Finding (`rule`) | What to do |
| - | - |
| `eval`, `function-constructor`, `string-timer`, `constructor-constructor` | Remove code built from strings: read data with `JSON.parse`, pass a function to `setTimeout`. |
| `dynamic-import`, `remote-import`, `unbundled-import` | Install the package and import it by name, so the bundle holds it; `import()` only a literal path. |
| `node-builtin` | Use the Web APIs, or a package that does not import `node:`. |
| `no-fetch-handler` | Export the handler from the entry: `export default { async fetch(request, env, ctx) { … } }`. |
| `raw-socket` | Use `fetch()` to a host in `allowed_hosts`: sockets are not available. |
| `host-not-allowed` | Add the host to `allowed_hosts` (a new version: the merchant consents to it), or remove the request. |
| `tassyir-host` | Call Tassyir through `ctx.props.TASSYIR`, never over the network. |
| `not-https` | Use `https://` (or `wss://`). |
| `dynamic-host` (warns) | A host built at run time: only `allowed_hosts` will answer it. |
| `scope-not-requested` | Request the scope the route needs in the manifest, or remove the call. |
| `bidi-control`, `invisible-run`, `hidden-character`, `invisible-identifier` | Remove the invisible characters: a reader of the code cannot see what it does. |
| `too-large`, `too-many-files` | Make the bundle smaller: minify, and leave out what the Worker does not import. |

### Where a version stands

`tassyir app version` shows it, and `deploy` exits by it:

| The version | Exit | Next step |
| - | - | - |
| Released: scanned, then deployed | 0 | Installations get it as an update; new installations get it at once when it is the latest. |
| Held for a person (`in_review`) | 0, `"released": false` | A person at Tassyir releases or rejects it; `tassyir app version <n> --follow` waits. |
| Failed its scan (`VERSION_SCAN_FAILED`) | 1, each finding in `errors` | Fix every finding, then deploy again: a new bundle is a new version. |
| Its scan ended without a verdict (`SCAN_TIMED_OUT`, …) | 5 | Deploy the same bundle again: it is scanned again. |
| Scanned, but the deployment failed | 1, its code (`CLOUDFLARE_REJECTED`, …) | The message carries what Cloudflare answered (`10021`: the Worker failed to start); fix it and deploy a new version. |
| Rejected by a person at Tassyir | 1, `VERSION_REJECTED` | Change the app as the reason says, then deploy again. |
| Still scanning at `--timeout`, or after Ctrl-C | 5, `VERSION_IN_PROGRESS` | `tassyir app version <n> --follow` picks it up; stopping never stops the scan. |

## Call the Admin API

`ctx.props.TASSYIR` calls the Admin API as the installation, with no token:
the same routes, scopes, store access and answers as an access token of the
installation, from the [Admin API](/guides/admin-api) and its reference.
`hostedAdmin(props, { retries, timeoutMs, onResponse })` from `@tassyir/app`
is the typed client over it: the same `AdminClient` an app on your server
uses, its requests sent through `ctx.props.TASSYIR.fetch` with no
`Authorization` header, and no token to hold or refresh.

```ts theme={null}
import {
  HOSTED_BINDING_ERRORS,
  hostedAdmin,
  isTassyirError,
} from '@tassyir/app';
import type { HostedProps } from '@tassyir/app';

export async function confirm(
  props: HostedProps,
  orderId: string,
): Promise<void> {
  const client = hostedAdmin(props, { retries: 2, timeoutMs: 10_000 });
  try {
    await client.post('/orders/{id}/confirm', {
      path: { id: orderId },
      idempotencyKey: `confirm-${orderId}`,
    });
  } catch (error) {
    // The binding's own refusals never reached the API: no requestId.
    if (isTassyirError(error) && error.code in HOSTED_BINDING_ERRORS) {
      console.warn(`TASSYIR refused the call: ${error.code}`);
    }
    throw error;
  }
}
```

Each call is one of the request's 50 subrequests, and so is each retry. What
the binding sends:

* **Only Admin API paths:** `/apps/<version>/` and segments of letters,
  digits, `_` and `-`; no other path, no `//`, trailing `/`, `%` or `;`. The
  URL's host does not matter: the call always goes to Tassyir's API. The one
  exception is a `GET` of Tassyir's two public key documents
  ([below](#webhooks)).
* **Only GET, POST, PUT, PATCH and DELETE, and only a JSON body** of at most
  100 KB. It is re-serialised before it is sent, so **send ids as strings**: a
  number past 2^53 would be rounded (the Admin API's ids always are strings).
* **Only three of your headers pass:** `Accept`, `Content-Type` and
  `Idempotency-Key` (1 to 255 printable ASCII characters). Retrying a write
  with the same key is safe, as for any app.
* **The answer** is the API's, at most 8 MiB, with `Content-Type`, the
  `RateLimit-*` headers, `Retry-After`, `Idempotent-Replayed` and
  `X-Request-Id`. Ask for less with `limit` or `?fields=`.
* **The installation acts**, never the viewer: the activity log names your
  app. Rate limits are the installation's, as for any app.

Some refusals come from the binding itself, before the call reaches the API,
in the same problem shape without a `requestId` (`HOSTED_BINDING_ERRORS`
lists them with their status and meaning, and `hostedAdmin` throws them as
`TassyirApiError`s, like the API's):
[`HOSTED_PATH_NOT_ALLOWED`](/guides/errors#hosted_path_not_allowed),
[`RESPONSE_TOO_LARGE`](/guides/errors#response_too_large),
[`TASSYIR_BINDING_NOT_AVAILABLE`](/guides/errors#tassyir_binding_not_available),
and `METHOD_NOT_ALLOWED`, `BAD_REQUEST`, `IDEMPOTENCY_KEY_INVALID`,
`PAYLOAD_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `SERVICE_UNAVAILABLE` (the API
did not answer in 30 seconds). `hostedAdmin` never retries
`RESPONSE_TOO_LARGE` or `TASSYIR_BINDING_NOT_AVAILABLE`. The API answers
`HOSTED_CALL_REFUSED` (401) when the installation can no longer call it:
uninstalled, suspended, or no longer on a released version.

`ctx.props.TASSYIR.fetch` can also be called as it is, with the Admin API's
full URLs (`https://api.tassyir.io/apps/2026-10/orders`); the rules above are
the same.

## Storage

Each installation has its own SQLite database, `ctx.props.STORAGE`:

| Method | Answer |
| - | - |
| `sql(query, ...bindings)` | `{ rows, rowsRead, rowsWritten }`; the last statement's rows |
| `batch([{ query, bindings? }, …])` | One result per statement, all in one transaction |
| `usage()` | `{ bytes, limitBytes }` |

```ts theme={null}
import type { HostedStorage } from '@tassyir/app';

export async function remember(
  STORAGE: HostedStorage,
  orderId: string,
  stars: number,
): Promise<void> {
  // One call: one transaction and one subrequest, the schema included.
  await STORAGE.batch([
    {
      query:
        'CREATE TABLE IF NOT EXISTS reviews (order_id TEXT PRIMARY KEY, stars INTEGER)',
    },
    {
      query: 'INSERT OR REPLACE INTO reviews (order_id, stars) VALUES (?, ?)',
      bindings: [orderId, stars],
    },
  ]);
}
```

* **Limits:** 50 MiB per installation; a query of at most 100,000
  characters; at most 100 bound values, 1 MiB together; a batch of at most
  50 statements; at most 5,000 rows and about 4 MiB in an answer (page with
  `LIMIT`).
* **Each call is one transaction:** a statement that fails, an answer too
  large or a database grown past its size rolls back everything the call
  wrote. Reads and deletes always run, so a full database can be emptied.
  `BEGIN`, `COMMIT` and most `PRAGMA`s are refused.
* **Errors** are thrown with a message that starts with `STORAGE_FULL`,
  `STORAGE_LIMIT`, `STORAGE_INVALID` or `STORAGE_UNAVAILABLE`, or SQLite's
  own message.
* **It is deleted 48 hours after the app is uninstalled**, with the
  installation's [app data](/guides/app-data)
  ([Compliance and uninstall](/guides/compliance-and-uninstall)).

## Call other services

Your code's `fetch()` reaches the hosts of `allowed_hosts` only: an exact
name, or `*.` + a name for its subdomains (never the name itself), over https
on port 443, with no user or password in the URL. Everything else is refused
with a `403` whose `tassyir-egress-refused` header says why (`not_allowed`,
`tassyir_host`, `not_https`, `port`, `credentials_in_url`, `ip_literal`,
`private_name`); the request is never sent. Tassyir's own domains are always
refused: call Tassyir through `ctx.props.TASSYIR`. A redirect is not followed: your code
gets the `3xx`, and following it is a new request, checked again. Sockets are
not available.

The merchant sees every host in `allowed_hosts` on the install screen, and a
version that adds one asks for their consent again.

## Webhooks

A hosted app receives the same deliveries as an app on your server, at
`https://{handle}.tassyir-apps.com` + the webhook `uri`: the same headers,
the same signed body ([Webhooks](/guides/webhooks)). Your handler runs with
`viewer` set to `null`, with the installation's `STORAGE` and `TASSYIR`.
Answer within 10 seconds; only your status and `Retry-After` are read. An
exception, or a request past its limits, counts as a failed attempt and is
retried.

Verify each delivery with `verifyHostedWebhook(request, ctx.props)` from
`@tassyir/app`:

```ts theme={null}
import {
  isTassyirError,
  TassyirVerificationError,
  verifyHostedWebhook,
} from '@tassyir/app';
import type { HostedProps } from '@tassyir/app';

export async function onWebhook(
  request: Request,
  props: HostedProps,
): Promise<Response> {
  try {
    const delivery = await verifyHostedWebhook(request, props);
    // At least once: deduplicate on delivery.id, or keep handlers idempotent.
    console.info(delivery.event.type);
    return new Response(null, { status: 200 });
  } catch (error) {
    if (
      isTassyirError(error, 'KEYS_UNAVAILABLE') ||
      isTassyirError(error, 'KEYS_NOT_CONFIGURED')
    ) {
      // Never process a delivery unverified: Tassyir delivers it again.
      return new Response(null, { status: 503 });
    }
    if (error instanceof TassyirVerificationError) {
      return new Response(null, { status: 400 });
    }
    throw error;
  }
}
```

It is `verifyWebhook`, every rule of it ([Webhooks](/guides/webhooks#verify-every-delivery)),
with your app, the installation and its business taken from `ctx.props`:

* **The signature is always verified**, by default with Tassyir's published
  keys read through the binding: `hostedWebhookKeys(props)`, a key source
  whose `fetch` is `ctx.props.TASSYIR.fetch`, reading
  `GET https://api.tassyir.io/apps/webhook-keys`. Make it per request, from
  that request's `ctx.props` (`verifyHostedWebhook` does): the binding
  belongs to its request, and a key source kept in a module variable would
  fetch through a dead one. Each delivery reads the document as Tassyir
  publishes it (one subrequest), so a key rotation needs no new version of
  your app.
* **It never skips the signature.** When the keys cannot be read it throws
  `KEYS_UNAVAILABLE` or `KEYS_NOT_CONFIGURED` (a `TassyirError`): answer 503,
  and Tassyir delivers the event again later.
* **A request with a viewer is refused** with `WEBHOOK_NOT_A_DELIVERY`: it
  came from a page of your app, not from Tassyir. Answer 400.
* **Never pin Tassyir's keys in your bundle.** Keys rotate, and a pinned key
  would stop verifying deliveries for every installation still on that
  version until its merchant accepts an update. The `keys` option is for
  tests: pass `WebhookKeys.fromPublicKeys([...])` with your own test keys.

The binding reads two public documents, and only with `GET`, at exactly these
paths (no query, no trailing `/`): `/apps/webhook-keys` (the webhook keys)
and `/apps/.well-known/jwks.json` (the ID token keys). Another method is
`METHOD_NOT_ALLOWED` (405, `Allow: GET`). They are the documents the API
publishes, read with no credential and served from a copy Tassyir Hosting
keeps for every app: read again after 5 minutes, and never served past the
API's own `max-age`, which the answer's `Cache-Control` carries.

**`app/uninstalled` and `business/redact` reach an uninstalled
installation too**, as they reach an app on your server. During those two
deliveries `TASSYIR` answers `HOSTED_CALL_REFUSED` (the installation is no
longer active) to Admin API calls; the key documents still read, so the
deliveries verify as usual. `STORAGE` still holds everything for
`app/uninstalled` (it is deleted 48 hours later) and nothing for
`business/redact`. Clean up what you keep elsewhere, through `fetch()` to
your `allowed_hosts`.

## Checklist

* Every host the code calls is in `allowed_hosts`; nothing calls Tassyir but
  `ctx.props.TASSYIR`.
* `ctx.props` read with `readHostedProps`, the Admin API called with
  `hostedAdmin`.
* Every delivery verified with `verifyHostedWebhook`, keys never pinned; 503
  on `KEYS_UNAVAILABLE` and `KEYS_NOT_CONFIGURED`.
* No `node:` import, and the entry exports a `fetch` handler.
* No page, webhook or link under `/.tassyir/`.
* No merchant data in module-level variables.
* Nothing changes on a `GET`.
* Ids are strings in every body.
* `tassyir deploy --dry-run` passes before you deploy; the scan's findings
  are fixed, not silenced.


# Tokens
Source: https://developers.tassyir.io/guides/tokens

Learn who is looking from the ID token, get and keep access tokens, and refresh them without locking a merchant out.

Your server needs two answers before it calls the Admin API: **who is
looking** (which person, business and installation) and **a token to call
with**. The ID token answers the first; offline and online access tokens the
second. `@tassyir/app` handles both, and this guide explains what it does so
you can rely on it.

| Token | Looks like | Lives | What it is for |
| - | - | - | - |
| Client id | `app_…` | forever | Names your app. Not a secret. |
| Client secret | `tsy_cs_…` | until rotated | Authenticates your server at the token endpoint. Shown once. |
| ID token | a JWT (`EdDSA`) | 60 seconds, exchanged once | Says who is looking at your page. The only proof of it. |
| Offline access token | `tsy_at_…` | 1 hour | Calls the Admin API as your app. Comes with a refresh token. |
| Refresh token | `tsy_rt_…` | 90 days, rotated on every use | Gets a new offline access token. |
| Online access token | `tsy_at_…` | 1 hour | Calls the Admin API for one person. No refresh token. |
| Install code | `tsy_ic_…` | 5 minutes, one use | A headless app's first tokens. |

Every one of them but the client id is a secret: keep it on your server, and
never log it or put it in a page, a URL or a repository.

## Set up the SDK

Create one `TassyirApp` per process. It needs your client id and secret, your
app's numeric id (to verify webhooks), and a **token store**: where each
installation's offline tokens live. A store must be durable (a `set` that
resolved survives a crash) and must return the latest `set`.

```ts theme={null}
import { createTassyirApp, type TokenSet, type TokenStore } from '@tassyir/app';

/** Your durable storage: a database table, a key-value store. */
export interface KeyValue {
  get(key: string): Promise<string | undefined>;
  set(key: string, value: string): Promise<void>;
  delete(key: string): Promise<void>;
}

export function createTassyir(kv: KeyValue) {
  // Encrypt the tokens at rest in a real deployment: they are secrets.
  const tokenStore: TokenStore = {
    async get(installationId) {
      const value = await kv.get(`tassyir:tokens:${installationId}`);
      return value === undefined ? undefined : (JSON.parse(value) as TokenSet);
    },
    async set(installationId, tokens) {
      await kv.set(`tassyir:tokens:${installationId}`, JSON.stringify(tokens));
    },
    async delete(installationId) {
      await kv.delete(`tassyir:tokens:${installationId}`);
    },
  };

  return createTassyirApp({
    clientId: setting('TASSYIR_CLIENT_ID'), // app_…
    clientSecret: setting('TASSYIR_CLIENT_SECRET'), // tsy_cs_…
    appId: setting('TASSYIR_APP_ID'), // the numeric id in the console
    tokenStore,
    retries: 3,
  });
}

function setting(name: string): string {
  const value = process.env[name];
  if (!value)
    throw new Error(`Set ${name}: see your app in the developer console`);
  return value;
}
```

`MemoryTokenStore` exists for tests only: it forgets everything on restart.
The [`@tassyir/app` README](https://github.com/tassyir/apps-sdk/tree/main/packages/app#example)
has a complete server with a store and a refresh lock.

## Who is looking: the ID token

Your page in the dashboard asks App Bridge for an ID token
([Embedded pages](/guides/embedded-pages)) and sends it to your server, which
verifies it. **The ID token is the only proof of who is looking.** The address
your page is loaded at, its query string and App Bridge's context are not:
anyone can open your page's URL with any query string. Read the user, the
business and the installation from a verified ID token, nowhere else.

An ID token is a JWT signed with Ed25519 (`alg: "EdDSA"`):

| Claim | Meaning |
| - | - |
| `iss` | `https://api.tassyir.io/apps` |
| `aud` | your client id |
| `sub` | the dashboard user looking at your page |
| `bid` | the business |
| `iid` | the installation |
| `sid` | the dashboard tab's session, random |
| `locale` | `ar` or `en`, the dashboard's language |
| `iat`, `nbf`, `exp` | issued, valid from, expires: 60 seconds after issue |
| `jti` | the token's id |

`tassyir.verifyIdToken(token)` checks it the way Tassyir does: `alg: EdDSA`
only, the key chosen by `kid` from
`GET https://api.tassyir.io/apps/.well-known/jwks.json` (cached an hour,
fetched again for an unknown `kid`), the signature before any claim, `iss`,
`aud` equal to your client id, and `exp`, `nbf` and `iat` with 30 seconds of
clock leeway. It returns `userId`, `businessId`, `installationId`,
`sessionId` and `locale`.

* **Ask for a new ID token for every request to your server.** It lives 60
  seconds, and the token endpoint accepts each one once.
* Accept ID tokens over https only: one is a bearer credential for a minute.
* A page may ask for 30 ID tokens a minute. A page that calls your server more
  often should batch its requests, or your server can open its own short
  session once it has verified a token.

## Embedded apps: one offline token per installation

`tassyir.authenticate(idToken)` verifies the ID token, then **reuses the
installation's stored offline token**, or exchanges the ID token for one and
stores it. Your server can then call the Admin API as your app for that
installation, from a page request, a webhook or a background job.

```ts theme={null}
import { TassyirVerificationError } from '@tassyir/app';

// GET /api/business, called by your page with a new ID token as a bearer.
export async function handle(request: Request): Promise<Response> {
  const header = request.headers.get('authorization') ?? '';
  const idToken = /^Bearer (\S+)$/.exec(header)?.[1];
  if (idToken === undefined) return new Response(null, { status: 401 });
  try {
    const { idToken: who } = await tassyir.authenticate(idToken);
    const { data: business } = await tassyir
      .admin(who.installationId)
      .get('/business');
    return Response.json({ business: business.name, user: who.userId });
  } catch (error) {
    if (error instanceof TassyirVerificationError) {
      return new Response(null, { status: 401 }); // not genuine, not yours, or expired
    }
    throw error;
  }
}
```

**Keep the offline token you have.** Each exchange for an offline token
starts a new refresh family, and an installation keeps at most 25: past that,
the oldest families are revoked. An app that exchanged on every page view
would revoke its own tokens.

## Online tokens: acting for a person

An online token acts for the dashboard user who opened your page. What it can
do is your app's scopes **and** that person's own permissions, in your
installation's stores **and** that person's stores. An online token whose
person may only see the orders assigned to them reads only those orders. Use
one when your app must respect what the person looking may see.

```ts theme={null}
export async function ordersForThisPerson(idToken: string) {
  const session = await tassyir.authenticate(idToken, { tokenType: 'online' });
  // An online token is not stored and cannot be refreshed: it lives an hour.
  const admin = tassyir.adminWithToken(session.tokens);
  const { data } = await admin.get('/orders', { query: { limit: 20 } });
  return data;
}
```

Changes made with an online token are still recorded under your app's name.
Each online exchange spends an ID token: get a new one from the page when the
online token expires.

## Headless apps: the install code

An app with no page (no `admin.page`) and an `auth.callback_url` gets its
first tokens from an **install code**. Right after the install, the dashboard
sends the merchant's browser to your callback with `?code=tsy_ic_…`. The code
is valid 5 minutes, once, and only your client secret can redeem it.

```ts theme={null}
// GET <auth.callback_url>?code=tsy_ic_…
export async function callback(request: Request): Promise<Response> {
  const code = new URL(request.url).searchParams.get('code');
  if (code === null) return new Response('Missing code', { status: 400 });
  const tokens = await tassyir.redeemInstallCode(code); // stored for you
  return new Response(`Installed on business ${tokens.businessId}`);
}
```

Tassyir never calls your callback itself: the merchant's browser does. Never
log the URL with its code. When the merchant later accepts a version that
changes your scopes, your callback receives a new code the same way.

## Refresh safely

An access token lives one hour. `tassyir.admin(installationId)` refreshes it
when needed, and every refresh **rotates** the refresh token: the old one is
spent.

* A spent refresh token presented again **within 60 seconds** of its rotation
  is accepted (an answer lost on the way).
* Presented **later**, it revokes the whole family: every refresh and access
  token issued from it. The merchant then has to reopen your page (an
  embedded app) or reinstall your app (a headless app).

`@tassyir/app`'s token manager is built so this does not happen:

* At most one refresh runs per installation in a process; concurrent callers
  share its result.
* The rotated token set is written to your store **before** the new access
  token is used. If the write fails, the call fails with
  `TOKEN_STORE_FAILED`, and the set is written again on the next call.
* A refresh whose answer was lost is retried with the same token for at most
  40 seconds, inside the 60-second grace.
* A refresh token the process already rotated is never presented again
  (`REFRESH_TOKEN_ALREADY_USED`), even if a stale store hands it back.

**More than one process?** Then two processes can refresh the same
installation at once. Pass a `refreshLock` (an object with
`withLock(key, task)`, built on a lock your processes share) to
`createTassyirApp`, and keep the tokens in a store every process reads. The
token set is read again inside the lock, so a process that waited uses the
fresh token instead of the spent one.

## When a token stops working

The Admin API answers **401 `APP_TOKEN_INVALID`** for every token it will not
take: expired, revoked, or of an installation that is no longer active. The
answer never says which.

| What happened | What follows |
| - | - |
| The access token expired | The SDK refreshes it and repeats the call once. |
| The merchant accepted a change of scopes | Every token is revoked; `app/scopes_updated`. The next page view (or a new install code) gets new ones. |
| The merchant uninstalled the app | Every token is revoked; `app/uninstalled`. Forget the installation's tokens. |
| Tassyir suspended the installation or the app | Its tokens are revoked, and every call is refused. |
| A refresh family was revoked | The refresh is refused (`invalid_grant`); the SDK drops the stored set, and the next page view exchanges again. |

Forget an installation's tokens with `tassyir.tokens.forget(installationId)`
when you receive `app/uninstalled` or `app/scopes_updated`.

## Client secrets

Create secrets in the console's **Credentials** tab. A secret is shown once;
Tassyir keeps only a hash and its first characters (`tsy_cs_Ab3xY9Qz`), so a
lost secret means a new one.

* **Rotate** by creating a new secret: every active secret keeps working for
  24 more hours, so you can deploy the new one first (a secret already in its
  24 hours keeps its end).
* An app has at most 3 live secrets, and a developer may create 10 an hour.
* **Revoke** a leaked secret in the console: the token endpoint refuses it at
  once. Access tokens already issued live out their hour; refreshing needs a
  live secret.

## The token endpoint, without the SDK

`POST https://api.tassyir.io/apps/oauth/token`, with your client id and
secret as HTTP Basic authentication (never a `client_secret` parameter) and
form-encoded parameters (a flat JSON object works too):

| Grant | Parameters |
| - | - |
| ID token | `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`, `subject_token=<ID token>`, `subject_token_type=urn:ietf:params:oauth:token-type:id_token`, and optionally `requested_token_type=urn:tassyir:params:oauth:token-type:online-access-token` (the default is `…:offline-access-token`) |
| Install code | `grant_type=authorization_code`, `code=tsy_ic_…` |
| Refresh token | `grant_type=refresh_token`, `refresh_token=tsy_rt_…` |

```bash theme={null}
curl https://api.tassyir.io/apps/oauth/token \
  -u "$TASSYIR_CLIENT_ID:$TASSYIR_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"
```

```json theme={null}
{
  "access_token": "tsy_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tsy_rt_…",
  "refresh_token_expires_in": 7776000,
  "scope": "read_orders read_products write_orders",
  "installation_id": "755000000000000001",
  "business_id": "632000000000000001"
}
```

* `refresh_token` and `refresh_token_expires_in` (90 days) come with offline
  tokens only; `user_id` with online tokens only; `issued_token_type` with an
  ID-token exchange only.
* `scope` is the installation's granted scopes, implied ones included. The
  `scope` parameter of the request is ignored.
* Errors are OAuth's `{ "error", "error_description" }`, not problem+json:
  `invalid_client` (401: the client id or secret, or a `client_secret` in the
  body), `invalid_grant` (an ID token, code or refresh token that is invalid,
  expired, used, revoked or another app's), `invalid_request`,
  `unauthorized_client` (the app is suspended), `unsupported_grant_type`,
  `slow_down` (429, with `Retry-After`) and `temporarily_unavailable` (503,
  with `Retry-After`).
* Each app may make 300 token requests a minute.

The full list is in [Errors](/guides/errors#token-endpoint-errors).


# Webhooks
Source: https://developers.tassyir.io/guides/webhooks

Subscribe to a business's events, verify each signed delivery, handle retries and replays once, and test your endpoint.

Tassyir tells your app what happens on the businesses that installed it: an
order created, confirmed or delivered, a product changed, stock moved, the
app uninstalled. Each event is a signed HTTPS `POST` to your server, sent at
least once and in no particular order. Verify every delivery, answer fast,
and handle each one once.

## Subscribe

List the topics in the manifest, each with the address that receives it:

```toml theme={null}
[[webhooks]]
topics = ["orders/created", "orders/delivered", "app/uninstalled"]
uri    = "/webhooks"
```

`uri` is a path on your `hosting.url`, or an absolute https URL. A topic is
subscribed once in the whole manifest, and needs the scope that reads its
resource. A new topic takes effect on an installation once its merchant
accepts the version that adds it.

## Topics

| Topic | Fires when | `data` | Needs |
| - | - | - | - |
| `orders/created` | a real order is created (or a checkout becomes one) | `order` | `read_orders` |
| `orders/confirmed`, `orders/cancelled`, `orders/dispatched`, `orders/delivered`, `orders/returned` | the order reaches that stage | `order` | `read_orders` |
| `orders/updated` | anything else an app can read changes; `changed` names it | `order` | `read_orders` |
| `abandoned_checkouts/created` | a buyer leaves a checkout unfinished | `checkout` | `read_orders` |
| `products/created`, `products/updated` | a product is created, or reads differently | `product` | `read_products` |
| `products/deleted` | not sent today: no product is deleted (see below) | `product` | `read_products` |
| `inventory_levels/updated` | a stock item's levels, low-stock threshold or low flag change | `inventoryLevel` | `read_inventory` |
| `customers/updated` | a customer reads differently | `customer` | `read_customers` |
| `offers/created`, `offers/updated`, `offers/deleted` | an offer is created, reads differently, or is deleted | `offer` (`offers/deleted`: its id only) | `read_offers` |
| `app/installed`, `app/uninstalled`, `app/scopes_updated` | your installation is created, removed, or its scopes change | `installation` | none |
| `customers/data_request`, `customers/redact`, `business/redact` | buyer data requests and the deletion after uninstall | see [Compliance](/guides/compliance-and-uninstall) | none |
| `bulk/finished` | a bulk export your installation asked for is done, or failed | `bulkExport` | none |

* **`app/*`, `business/redact` and `bulk/finished` reach only the
  installation they are about**, never another app. Every other topic
  reaches each active installation of the business that subscribes to it and
  was granted its scope.
* **An installation limited to selected stores** receives order, checkout,
  product and stock events of its stores only. Customer events carry that
  installation's stores' counters. Offer events carry the offer's store, and
  reach it for its own stores' offers ([Offers](/guides/offers#stores)).
* The resources (`order`, `product`, …) are the same as the Admin API's
  ([Orders](/guides/orders), [Products and collections](/guides/products-and-collections),
  [Stock](/guides/stock), [Customers](/guides/customers), [Offers](/guides/offers)),
  masked the same way.

## What you receive

```http theme={null}
POST /webhooks HTTP/1.1
content-type: application/json
user-agent: Tassyir-Webhooks/1.0 (+https://developers.tassyir.io)
webhook-id: dlv_741939488313319175
webhook-timestamp: 1760173964
webhook-signature: v1a,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4…
tassyir-topic: orders/delivered
tassyir-business-id: 632000000000000001
tassyir-api-version: 2026-10
```

```json theme={null}
{
  "id": "evt_741000000000000001",
  "type": "orders/delivered",
  "apiVersion": "2026-10",
  "createdAt": "2026-10-11T09:12:44.120Z",
  "businessId": "632000000000000001",
  "storeId": "632000000000000100",
  "appId": "741000000000000900",
  "installationId": "755000000000000001",
  "changed": ["delivered", "deliveredAt"],
  "data": { "order": { "id": "741000000000000500", "orderNumber": "1042" } }
}
```

| Header | Value |
| - | - |
| `webhook-id` | `dlv_…`: one per event per installation, **the same on every retry and replay**. Deduplicate on it. |
| `webhook-timestamp` | Unix seconds of this attempt. |
| `webhook-signature` | `v1a,<base64 Ed25519 signature>`; several, space-separated, while Tassyir rotates its keys. |
| `tassyir-topic` | The topic. |
| `tassyir-business-id` | The business. |
| `tassyir-api-version` | The API version of the body: the one your installation's version uses. |
| `tassyir-test` | `true` on a test delivery only. |

The body is the **envelope**: `id` (`evt_…`), `type`, `apiVersion`,
`createdAt` (when the event happened), `businessId`, `storeId` (may be
`null`), `appId` and `installationId` (check both are yours), `changed` and
`data`, one key per topic.

**`data` is read when the delivery is built**, seconds after the event, so it
can be newer than the event. Reconcile by the resource's `updatedAt`, and read
the resource again through the Admin API when you are unsure. Ignore fields
you do not know: a version may add fields, never rename or remove one.

## Verify every delivery

Tassyir signs `{webhook-id}.{webhook-timestamp}.{body}` with Ed25519 (Standard
Webhooks, scheme `v1a`). Verify the **raw body**, the exact bytes you
received: parsing the JSON and serialising it again breaks the signature.

```ts theme={null}
import { isTassyirError, TassyirVerificationError } from '@tassyir/app';

/** Where you keep installations and handled deliveries. */
export interface WebhookState {
  isInstallation(installationId: string): Promise<boolean>;
  hasHandled(webhookId: string): Promise<boolean>;
  /** Records a webhook-id, once its event is handled (or durably queued). */
  markHandled(webhookId: string): Promise<void>;
}

// POST /webhooks
export async function receive(
  request: Request,
  state: WebhookState,
): Promise<Response> {
  let delivery;
  try {
    delivery = await tassyir.verifyWebhook(request, {
      // A delivery can arrive before app/installed: refuse it, Tassyir retries.
      installationId: async (id, event) =>
        event.type === 'app/installed' || (await state.isInstallation(id)),
      testDeliveries: 'accept',
    });
  } catch (error) {
    if (isTassyirError(error, 'KEYS_UNAVAILABLE'))
      return new Response(null, { status: 503 });
    if (error instanceof TassyirVerificationError)
      return new Response(null, { status: 400 });
    throw error;
  }
  if (delivery.test) return new Response(null, { status: 200 });

  // At least once: a webhook-id you already handled is answered and skipped.
  if (await state.hasHandled(delivery.id)) {
    return new Response(null, { status: 200 });
  }

  switch (delivery.event.type) {
    case 'orders/delivered': {
      const { order } = delivery.event.data;
      console.log(
        `order ${order.orderNumber} delivered, ${order.total ?? '?'} ${order.currency}`,
      );
      break;
    }
    case 'app/uninstalled':
      await tassyir.tokens.forget(delivery.installationId);
      break;
  }
  // Only now: if handling threw, Tassyir retries, and the retry is handled.
  await state.markHandled(delivery.id);
  return new Response(null, { status: 200 });
}
```

`tassyir.verifyWebhook` checks, in order:

1. the `v1a` signature, against the keys of
   `GET https://api.tassyir.io/apps/webhook-keys` (cached an hour, fetched
   again when no key verifies). During a key rotation a delivery carries
   several signatures; any one that verifies is enough;
2. the timestamp, within 5 minutes of now;
3. the envelope's `appId` (your numeric app id, `TASSYIR_APP_ID`: not the
   `app_…` client id) and `installationId` (your check);
4. the unsigned `tassyir-*` headers agree with the signed envelope.

`delivery.event` is typed per topic: `switch (delivery.event.type)` narrows
`data`. If the keys cannot be fetched once the cached copy has expired, it
throws `KEYS_UNAVAILABLE`: answer 503, and Tassyir delivers again later.

**Without the SDK:** decode each `whpk_…` key of the keys document (base64 of
the raw 32-byte Ed25519 public key), split `webhook-signature` on spaces,
keep the `v1a,` entries, and accept the delivery when one of them verifies
`{webhook-id}.{webhook-timestamp}.{raw body}` under one of the keys, the
timestamp is within 5 minutes, and `appId` and `installationId` are yours.

## Answer within 10 seconds

* Answer **2xx** as soon as the delivery is verified and recorded; do slow
  work afterwards, from a queue. Tassyir does not read your answer's body.
* Tassyir waits 10 seconds for the connection and your answer's headers, and
  follows no redirect: a 3xx is a failed attempt.
* Your endpoint must be https on port 443, at a public hostname.

## Retries, and disabled endpoints

| Your answer | What Tassyir does |
| - | - |
| 2xx | Delivered. |
| 410 Gone | Failed, and **disables the installation's webhooks at once**. |
| Anything else: 4xx, 5xx, 3xx, a timeout, no connection | Retries after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h and 24 h (about 3 days), then gives up. A longer `Retry-After` is honoured, up to 24 hours. |

* **Three days of continuous failure** disables the installation's webhooks,
  and Tassyir emails you, at most once a day per app. Any 2xx resets the
  clock.
* Disabling is per installation, for all its topics. Until you re-enable it
  in the developer console, its events are recorded as skipped and never
  sent. Fix your endpoint first: a 410 or three more days of failure
  disables it again. Then replay the skipped deliveries that matter.
* A delivery still pending four days after its event fails.

## Handle each event once

Delivery is **at least once, in no particular order**. The same delivery can
arrive twice (a retry after your answer was lost, a replay), and
`orders/delivered` can arrive before `orders/dispatched`.

* Deduplicate on `webhook-id`: it is the same on every retry and replay of a
  delivery. Keep the ids for at least a week (replays are possible for 7
  days).
* Record a `webhook-id` only once its event is handled, or saved to a durable
  queue that will handle it. An id recorded before a failed attempt makes the
  retry look handled, and the event is lost. Two copies of one delivery can
  still race: make what an event does safe to do twice.
* Never rely on order: compare the resource's `updatedAt` with what you
  hold, and read it again when unsure.
* An event for an installation you do not know yet (it overtook
  `app/installed`) can be refused with a 4xx: it is retried.

## How events are recorded

* **One fact, one event.** Confirming, cancelling, dispatching, delivering or
  returning an order sends that topic. `orders/updated` is sent for every
  other change an app can read (the buyer, the items, the delivery and the
  carrier's status, scheduling, archiving, a waiting order unlocking, a
  discount added or removed), with `changed` naming the order's top-level
  fields (`subtotal`, `discountTotal` and `discounts` among them: see
  [Order money](/guides/orders#order-money)). A write that also changed
  fields outside its topic's own sends `orders/updated` for those too.
* **`orders/created` is sent once per real order.** An abandoned checkout is
  `abandoned_checkouts/created`; when it becomes an order (same id),
  `orders/created` is sent then.
* **A returned order keeps its status** (usually `pending`): read the
  `returned` flag.
* **Carriers.** A carrier's status change is `orders/updated` with `changed`
  naming `delivery` (and `status` when the order's status moved with it). A carrier update that changes nothing sends nothing.
* **Products.** `products/updated` names the product's top-level fields that
  changed (`price`, `variants`, `images`, `active`, `collectionIds`, …). A
  deactivated product is `products/updated` with `active: false`: no product
  is ever deleted, so `products/deleted` is not sent today.
* **Stock.** `inventory_levels/updated` is sent once per stock item per
  change, with `changed` empty: the body is the item's whole stock. Stock can
  be negative after a dispatch shortfall; it is sent as it is.
* **Customers.** `customers/updated` is sent when a customer reads
  differently, never when it was only recomputed.
* **Offers.** `offers/created` when an offer is created (always a draft),
  `offers/updated` when it reads differently (`changed` names the fields:
  publishing, pausing, archiving, dates, rules, targets and the code count),
  and `offers/deleted` when a never-redeemed one is deleted. A redeemed offer
  is archived, never deleted. See [Offers](/guides/offers#webhooks).

## Test, replay and read the log

In the developer console:

* **Send a test** (the **Installs** tab): a synthetic event of one topic your
  installation subscribes to, with sample data (order `TEST-1001`, buyer "Test
  Buyer"), signed and sent like a real delivery. It is marked by the header
  `tassyir-test: true`, a `webhook-id` of `dlv_test_…` and the envelope id
  `evt_0`; its `businessId`, `appId` and `installationId` are real. It is
  never retried, never logged, and never disables your endpoint.
  `@tassyir/app` refuses test deliveries (`WEBHOOK_TEST_DELIVERY`) unless you
  pass `testDeliveries: 'accept'`; then `delivery.test` is true.
* **Read the log** (the **Webhook deliveries** tab): every delivery of the
  last 30 days, metadata only (status, HTTP status, error, duration,
  attempts), never a body.
* **Replay** a delivery: one more attempt now, with the **same `webhook-id`**
  and a body rebuilt from the resource as it is now. A failed replay is final
  (no retry follows). A delivery can be replayed while its event is kept, 7
  days.

A delivery's `status` is `pending`, `delivered`, `failed` or `skipped`. The
error codes the log shows:

| Error | Meaning |
| - | - |
| `HTTP_<status>`, `HTTP_410_GONE`, `HTTP_3xx_REDIRECT_NOT_FOLLOWED` | Your endpoint answered, but not 2xx. |
| `TIMEOUT` | No answer within 10 seconds. |
| `DNS_FAILED`, `CONNECTION_REFUSED`, `CONNECTION_RESET`, `HOST_UNREACHABLE`, `TLS_ERROR`, `NETWORK_ERROR` | The connection failed. |
| `BLOCKED_ADDRESS`, `URL_NOT_ALLOWED` | Tassyir will not send to that address (a private or reserved one). |
| `EXPIRED` | Still pending four days after the event. |
| `ENDPOINT_DISABLED` | Skipped: the installation's webhooks are disabled. |
| `INSTALLATION_INACTIVE`, `APP_SUSPENDED` | Skipped: the installation or the app cannot receive now. |
| `TOPIC_NOT_SUBSCRIBED`, `SCOPE_NOT_GRANTED`, `OUTSIDE_STORE_ACCESS` | Skipped: the installation's version, scopes or stores exclude it. |
| `NO_BODY`, `EVENT_EXPIRED` | Skipped: the resource is gone, or this installation may not see it. |


# Write offers and codes
Source: https://developers.tassyir.io/guides/write-offers

Create and run offers and their codes with write_offers, mint influencer codes in bulk, read redemptions, and ship an app-owned offer type with a declarative rule.

With `write_offers` an app runs offers of its own: an influencer platform that
mints a code per influencer, a spin-to-win wheel, a referral program, a
flash-sale scheduler, a "mix and match" the merchant can create from your
app. It creates an offer, adds codes to it, publishes, pauses and archives it,
and reads who used it. [Offers](/guides/offers) is the read side and the
description of an offer; read it first.

| Route | Does | Scope |
| - | - | - |
| `POST /offers` | Create an offer (always a draft) | `write_offers` |
| `PATCH /offers/{id}` | Change an offer | `write_offers` |
| `POST /offers/{id}/publish`, `/pause`, `/resume` | Put it live, stop it, start it again | `write_offers` |
| `DELETE /offers/{id}` | Delete it, or archive it if it was used | `write_offers` |
| `POST /offers/{id}/codes`, `POST /offers/{id}/codes/bulk` | Add one code, or up to 250 | `write_offers` |
| `POST /offers/{id}/codes/{codeId}/disable`, `/enable` | Stop a code, or start it again | `write_offers` |
| `GET /offers/{id}/codes` | List the codes of an offer you own | `read_offers` |
| `GET /offers/{id}/redemptions` | List the uses of an offer you own | `read_offers` |

`write_offers` implies `read_offers`, so you read every offer of the merchant
and the offers webhooks. It is a normal scope, and like any scope added after
an app was installed, an installation does not hold it until the merchant
accepts a version of your app that asks for it
([Scopes and consent](/guides/scopes-and-consent)). A call without it answers 403
`PERMISSION_DENIED`, with a `fix` that names the scope. An **online** token
also needs the person's own permission to create, change and delete offers.

No particular plan is needed, but the plan's limit on live offers (a Starter
merchant's three) applies to your offers exactly as to the merchant's: publish
and resume answer 403 `PLAN_LIMIT_REACHED` past it. And an offer prices an
order only on a business where Tassyir's order pricing is on, which is rolled
out business by business: until then an offer you create is stored, listed and
published, but takes nothing off an order.

## You write only the offers you own

An offer your app creates is **owned by your installation**; there is no field
to set that. The rule:

* **You change, and read the codes and redemptions of, only the offers your own
  installation created.** A write on the merchant's offer, or on another
  app's, is 403 `OFFER_NOT_OWNED`, and so is reading its codes or redemptions.
  The `fix` says what to do: create your own offer and change that one.
* An offer the token cannot see (an id that does not exist or is malformed,
  another business's, a store outside the installation's stores) is 404
  `NOT_FOUND` on every route, writes included.
* **Reads stay as they are.** You list and read every offer your token can
  see. `appOwned` is true for any app's offer, so it does not say "yours":
  keep the ids of the offers you create, and a 403 tells you the rest.
* **The merchant keeps control.** The dashboard writes every offer, an app's
  included: pause it, archive it, add codes. You hear about it with
  `offers/updated`; that is not an error of yours.
* Uninstalling leaves your offers as they are. A new installation of the same
  app does not own them: the merchant manages them in the dashboard.
* A store-limited installation creates offers in its own stores only: a
  `storeId` outside them is HTTP 460 `STORE_SCOPE_FORBIDDEN`
  ([Admin API conventions](/guides/admin-api#stores-460-and-404)).

## Create an offer

An offer is created as a **draft**, then published. `config` is the offer's
rule **in the shape the Offers page stores it**, which is not the shape
`GET /offers` answers (money is a number of whole dinars, a quantity tier
carries `price`). Every field is checked by the same rules as the dashboard.

| Field | Rule |
| - | - |
| `storeId` | **Required.** The store the offer belongs to: an offer has exactly one. A store that is not the business's is 404 `OFFER_STORE_NOT_FOUND` |
| `kind`, `method` | **Required, and never changed.** `kind`: `quantity`, `free_delivery`, `product_discount`, `order_discount`, `bxgy`, `addon` or `app`. `method`: `automatic`, or `code` (the buyer types one of the offer's codes) |
| `title` | **Required.** The merchant's own name for the offer, 1 to 100 characters |
| `label` | What the buyer reads, `{ "ar": "…", "fr": "…", "en": "…" }`, each at most 120 characters |
| `config` | The kind's settings, below |
| `combinesWith`, `eligibility` | Merged into the kind's defaults, key by key ([the offer](/guides/offers#the-offer)) |
| `totalUsageLimit`, `perBuyerLimit` | Whole numbers from 1, or `null` for none. `perBuyerLimit` counts per phone number and may not exceed `totalUsageLimit` |
| `startsAt`, `endsAt` | An ISO date-time, or `YYYY-MM-DD`: a business day in Africa/Algiers (the first and the last instant of that day) |
| `targets` | `[{ role?, refType, refId? }]`: what the offer applies to. `refType` is `all`, `product`, `variant` or `collection`, and each must belong to the offer's store. Which roles a kind takes is below |
| `codes` | `method: "code"` only: up to 250 `{ code, usageLimit? }` added with the offer |

`config` per kind (money is whole dinars; an unknown key is `OFFER_INVALID`
with `UNKNOWN_FIELD`):

| `kind` | `config` | Targets |
| - | - | - |
| `quantity` | `{ priceMode, tiers: [{ pieces, price, label, preselected, freeDelivery }] }`; `priceMode` `total`, `percent` or `amount_each` | `product` or `variant`, role `buy` |
| `free_delivery` | `{ threshold: { kind: "pieces" \| "amount", value }, delivery: "home" \| "desk" \| "both", wilayas }` | none (store-wide) |
| `product_discount` | `{ valueType: "percent" \| "fixed", value, maxAmount?, showCountdown? }` | `all` alone, or products, variants and collections |
| `order_discount` | `{ valueType: "percent" \| "fixed", value, maxAmount?, minimum: { kind: "pieces" \| "amount", value } \| null }` | none |
| `bxgy` | `{ buy: { pieces }, get: { pieces, discount }, maxPerOrder }`: buy 2, get 1 free | `buy` (required to publish) and `get` |
| `addon` | `{ price: { type, value }, maxQuantity, beforeSubmit, afterSubmit }`: a product offered next to the order | `addon` (1 to 5 products or variants, required) and `buy` |
| `app` | `{ typeHandle, rule }`: an offer of one of your own types, [below](#your-own-offer-types) | none (the rule names its lines) |

You read an offer back in the block of its kind (`quantity`, `freeDelivery`,
`productDiscount`, `orderDiscount`, `bxgy`, `addon` or, for an app's own kind,
`appRule`), in the shape [Offers](/guides/offers#the-kinds) describes.

A **draft** is saved as long as everything present is well formed; **publish**
also checks completeness (a title, the kind's required settings, at least one
target where the kind needs one, at least one enabled code for a `code`
offer, an `endsAt` not in the past). A refusal is 400 `OFFER_INVALID` with
`errors`, a list of `{ field, code }` where `field` is a dotted path
(`config.tiers.1.pieces`) and `code` says why (`REQUIRED`, `INVALID_VALUE`,
`UNKNOWN_FIELD`, `TOO_LARGE`, `NOT_WHOLE_DINARS`, `NOT_ASCENDING`,
`ALL_IS_EXCLUSIVE`, …). Act on `code`, show `field` to your user.

## Influencer codes, in bulk

The classic: one offer, one code per influencer, each with its own usage
limit. Codes are **unique across the business**, whatever the case (`SARA10`
and `sara10` are one) and whether disabled or not, are 3 to 30 letters,
digits, `-` or `_`, and are never reused: disabling keeps a code's spelling
and its history.

```ts theme={null}
import { addOfferCodes } from '@tassyir/app';

const influencers = ['SARA10', 'OMAR10', 'LINA10'];

// 1. A draft: 10% off everything, only with a code, until the end of the year.
const { data: offer } = await admin.post('/offers', {
  body: {
    storeId: '741000000000000100',
    kind: 'product_discount',
    method: 'code',
    title: 'Autumn influencers',
    label: { ar: 'خصم المؤثرين' },
    config: { valueType: 'percent', value: 10 },
    targets: [{ refType: 'all' }],
    perBuyerLimit: 1,
    endsAt: '2026-12-31',
  },
});

// 2. One code each. 250 per call is the API's limit: addOfferCodes cuts the
// list into calls of 250 and gathers the answers in the order you sent.
const added = await addOfferCodes(
  admin,
  offer.id,
  influencers.map((code) => ({ code, usageLimit: 50 })),
);

// The call is partial by design: a code that cannot be created is reported on
// its own entry and the others are created.
const refused = added.results.filter((entry) => entry.outcome !== 'created');
for (const entry of refused) console.warn(entry.code, entry.outcome);

// 3. Put it live (at least one enabled code is required for a code offer).
await admin.post('/offers/{id}/publish', { path: { id: offer.id } });
```

Each entry of a bulk answer's `results` has an `outcome`:

| `outcome` | Means |
| - | - |
| `created` | The code exists now |
| `taken` | The business already has this code (on any offer, disabled or not) |
| `invalid` | Not 3 to 30 letters, digits, `-` or `_` |
| `duplicate_in_request` | The same code twice in this call |

`POST /offers/{id}/codes/bulk` takes 1 to 250 codes (more is 400
`VALIDATION_FAILED` and nothing is written) and answers 200 whatever the mix.
A single `POST /offers/{id}/codes` answers 201, or 409 `OFFER_CODE_TAKEN`,
`OFFER_NOT_CODE_METHOD` (an automatic offer has no codes) or 400
`OFFER_CODE_INVALID`. Disable and enable are idempotent; `GET
/offers/{id}/codes` lists the codes newest first, disabled ones included:

```json theme={null}
{
  "id": "741000000000000300",
  "code": "SARA10",
  "usageLimit": 50,
  "uses": 12,
  "disabled": false,
  "disabledAt": null,
  "createdAt": "2026-10-02T10:00:00.000Z"
}
```

`uses` counts the redemptions that still count against `usageLimit` (held or
final): a cancelled order gives its use back. Codes appear nowhere else: the
offer, the webhooks and an order show a count, or nothing.

## Publish, pause, resume, delete

`publish`, `pause` and `resume` are **idempotent**: asking for the state the
offer is already in changes nothing and sends no event. Their body is
optional: send none, or `{ expectedVersion }` (below).

| Route | Does | Refused with |
| - | - | - |
| `publish` | Puts a draft live from its start date. An incomplete offer is 400 `OFFER_INVALID` | 403 `PLAN_LIMIT_REACHED`, 409 `OFFER_ARCHIVED` |
| `pause` | Stops a live offer pricing orders | 409 `OFFER_NOT_PUBLISHED` (a draft), `OFFER_ARCHIVED` |
| `resume` | Starts a paused offer again. An ended offer is not resumed: move its `endsAt` | 403 `PLAN_LIMIT_REACHED`, 409 `OFFER_NOT_PUBLISHED`, `OFFER_ENDED` |
| `DELETE` | An offer **nobody ever redeemed** is deleted with its codes and targets. One with any redemption is **archived** (status `ended`) | 403 `OFFER_NOT_OWNED` |

`DELETE` answers which it did, so you do not guess:

```json theme={null}
{ "id": "741000000000002000", "deleted": false, "archived": true }
```

`PATCH /offers/{id}` changes the fields you send, from the table above
(`kind` and `method` may be echoed back but never change: 400
`OFFER_KIND_IMMUTABLE`). `targets` and `config`, when sent, **replace** the
whole set; an empty body is 400. A live offer must stay publishable. Every
write on an offer can carry `expectedVersion`, the dashboard's compare and
set: a stale one is 409 `OFFER_VERSION_CONFLICT` with `currentVersion`. Without
it the change applies to the offer as it is when the request starts.

```ts theme={null}
const { data: changed } = await admin.patch('/offers/{id}', {
  path: { id: '741000000000002000' },
  body: { endsAt: '2027-01-15', totalUsageLimit: 1000 },
});
console.log(changed.status, changed.endsAt);
```

Writes are idempotent with an `Idempotency-Key`
([Admin API conventions](/guides/admin-api#idempotent-writes)); the typed client
sends one for you.

## Redemptions

`GET /offers/{id}/redemptions` is each use of an offer you own on an order,
newest first, in pages. `state` filters it: `held` (the order is not with a
carrier yet), `final` (handed over) or `released` (the order was cancelled, or
the buyer banned).

```ts theme={null}
// How many orders each code brought, counting the uses that stand.
const perCode = new Map<string, number>();
for await (const redemption of admin.paginate('/offers/{id}/redemptions', {
  path: { id: '741000000000002000' },
})) {
  if (redemption.state === 'released') continue;
  const code = redemption.code ?? 'automatic';
  perCode.set(code, (perCode.get(code) ?? 0) + 1);
}
console.log([...perCode]);
```

```json theme={null}
{
  "id": "741000000000000400",
  "orderId": "741000000000000401",
  "codeId": "741000000000000300",
  "code": "SARA10",
  "amount": "900.00",
  "currency": "DZD",
  "state": "final",
  "createdAt": "2026-10-04T10:00:00.000Z"
}
```

`amount` is what the offer took off that order, a decimal string. **Never a
buyer:** no name, phone or address. `orderId` is the one link: read the order
with `GET /orders/{id}` (`read_orders`, and `read_customer_contact` for the
buyer's contact fields, as for any order). An installation that owns the offer
but cannot read orders sees ids it cannot open. `codeId` and `code` are `null`
for an automatic offer, and `code` is `null` once the code was removed.

## Applying a code to an order

An app does not apply an offer to an order: orders get their offers from
Tassyir's pricing. When your app creates an order for a buyer who typed a
code, send it:

```ts theme={null}
const { data: order, rejectedCodes } = await admin.post('/orders', {
  body: {
    buyer: { name: 'Amina B.', phone: '+213555123456' },
    items: [{ productId: '741000000000000500', quantity: 2 }],
    codes: ['SARA10'],
  },
});

for (const entry of rejectedCodes ?? []) {
  console.log(`${entry.code} was not used: ${entry.reason}`);
}
console.log(order.discountTotal, order.discounts);
```

`codes` takes **one code at most** (case and surrounding spaces do not
matter). A code that does not apply never fails the order: the order is created
without it and `rejectedCodes` names the code with the reason (`code_unknown`,
`code_expired`, `code_used_up`, `not_eligible_audience`, `beaten_by`, …). The
order's `discounts[]` entry carries the code and `source: "code"`
([Order money](/guides/orders#order-money)). A usage limit that runs out between
the pricing and the write is 409 `OFFER_LIMIT_REACHED` and nothing is created.

## Webhooks

You hear your own writes, like any installation: the topics are
business-wide, so the app that created an offer receives `offers/created` for
it ([Offers](/guides/offers#webhooks)). A new offer is a draft, so `offers/updated`
with `changed` naming `status` and `publishedAt` is when it goes live; adding
or disabling a code sends `offers/updated` with `changed: ["codeCount"]`.
Deduplicate on `webhook-id`, and when two bodies of one offer arrive out of
order keep the one with the later `updatedAt`.

## Your own offer types

A native offer is one of the kinds above. An app can add **kinds of its own**
that the merchant creates from your app: "mix and match", a spin-to-win
prize, a loyalty tier. You declare each type in the manifest, and you write
its offers with `kind: "app"`. Pricing stays in Tassyir: an app-owned offer is
a **declarative rule**, JSON the pricing engine evaluates, so no code of yours
runs at checkout, it costs nothing at checkout and it can never fail an order.

Declare the types in `tassyir.app.toml` (at most 10; declaring any needs the
`write_offers` scope):

```toml theme={null}
name        = "Wheely"
handle      = "wheely"
api_version = "2026-10"

[access]
scopes = ["write_offers", "read_products"]

[access.scope_reasons]
write_offers  = "Create the offers your merchants set up in Wheely"
read_products = "Let a merchant pick the products an offer applies to"

[hosting]
mode = "external"
url  = "https://wheely.example.com"

[admin]
page = "/"

[[offers.types]]
handle      = "mix-match"
class       = "product"
path        = "/offers/mix-match"
label       = { ar = "اخلط واختر", en = "Mix and match" }
description = { ar = "القطعة الثالثة مجانًا", en = "The third piece free" }
```

| Field | Rule |
| - | - |
| `handle` | Required. 1 to 40 lowercase letters, digits and hyphens, starting with a letter or digit. Unique among your types |
| `class` | Required. `product`, `order` or `delivery`: the step the type's offers price in, with the stacking rules of a native offer of that class |
| `path` | Required. Your page that configures one offer of this type: a path on your origin (the `admin.page` rules, at most 200 characters) |
| `label` | Required. `{ ar, en }`, up to 50 characters each: what the merchant reads under "From your apps" |
| `description` | Optional. `{ ar, en }`, up to 200 characters each |

The merchant sees your types in the create dialog of the Offers page, **"From
your apps"**, for every active installation of your app that holds
`write_offers` (directly or implied) and may act on that store. Choosing one
opens your embedded page at the type's `path` ([Embedded pages](/guides/embedded-pages)),
which is where the offer is set up: your page creates the offer with the Admin
API, and later changes it.

```ts theme={null}
import type { AppOfferConfig } from '@tassyir/app';

// The third piece free on a collection, in two wilayas.
const config: AppOfferConfig = {
  typeHandle: 'mix-match',
  rule: {
    class: 'product',
    when: {
      all: [
        { 'lines.collection': '741000000000000900', 'quantity.gte': 3 },
        { 'delivery.wilaya.in': ['16', '31'] },
      ],
    },
    then: [
      { 'discount.cheapest': { percent: 100, count: 1 } },
      { label: { ar: 'القطعة الثالثة مجانًا', en: 'The third piece free' } },
    ],
  },
};

const { data: offer } = await admin.post('/offers', {
  body: {
    storeId: '741000000000000100',
    kind: 'app',
    method: 'automatic',
    title: 'Mix and match, autumn',
    config,
  },
});
```

`typeHandle` must be one of the `[[offers.types]]` of the version your
installation runs, else 400 `OFFER_INVALID` with `config.typeHandle:
NOT_DECLARED`. Every product, variant and collection the rule names must
exist in the offer's store (400 `OFFER_TARGET_NOT_FOUND` or
`OFFER_TARGET_OUTSIDE_STORE`).

* **The merchant manages the offer's life, you manage its settings.** On the
  Offers page an app-owned offer can be published, paused, resumed and
  archived (and its codes managed), but editing or duplicating it there
  answers 409 `OFFER_APP_OWNED`: it is changed in your app, at the type's
  `path`. Your own `PATCH` calls on your own offers are not affected.
* **It prices only while your installation is active and your app is not
  suspended.** Uninstalling, or a suspension, stops it pricing orders at once;
  the offer is kept, and reinstalling or resuming prices it again.
* An offer of a type is owned by the installation that created it, like any
  other offer of yours.

### The rule

A rule is `{ class, when?, then }`, validated on every write (400
`OFFER_INVALID`, with a coded issue per problem) and read again on every
price: a stored rule that no longer parses prices nothing, never fails an
order.

**`when`** is absent (always), a **leaf**, or `{ "all": [...] }` / `{ "any": [...] }` of 1 to 10 conditions, nested at most 3 deep (`TOO_DEEP`). A leaf is
an object with at least one of these keys (an empty one is `EMPTY`):

| Key | Tests |
| - | - |
| `lines.product`, `lines.variant`, `lines.collection` | Picks lines: an id, or 1 to 50. Every selector present in the leaf must match a line |
| `quantity.gte`, `quantity.lte` | Pieces, over the lines the leaf picked (the whole cart when it picked none) |
| `subtotal.gte`, `subtotal.lte` | Whole dinars, over the same lines |
| `delivery.wilaya.in` | Two-digit wilaya codes, `"01"` to `"69"` |
| `delivery.method` | `home` or `desk` |
| `channel.in` | Among `store`, `landing`, `shopify`, `dashboard`, `apps` |
| `audience` | `first_order` or `returning` |
| `time.between` | `{ "from": "18:00", "to": "23:59" }` on the Africa/Algiers clock; `from` after `to` spans midnight |

The lines a satisfied leaf picked are the lines the product actions apply to
(every priceable line when no leaf picked any).

**`then`** is 1 to 5 actions, each key once (`DUPLICATE`), at least one that
prices (`NO_ACTION`), all of the rule's `class` (`ACTION_CLASS_MISMATCH`):

| Class | Action | Value |
| - | - | - |
| `product` | `discount.lines` | `{ percent }` off each selected line, or `{ amount_each }` whole dinars off each piece |
| `product` | `discount.cheapest` | `{ percent, count }`: that percentage off the `count` cheapest selected pieces ("the third free") |
| `product` | `give.item` | `{ productId }` or `{ variantId }` (one of the two), `percent` (default 100), `count` (default 1): a gift |
| `order` | `discount.order` | `{ percent }` or `{ amount }` whole dinars off the goods |
| `delivery` | `delivery.waive` | `{}`: the quoted delivery fee is waived |
| any | `label` | `{ ar?, fr?, en? }` (120 characters each): buyer-facing text, prices nothing |

A **gift is never added by Tassyir**: when the rule is satisfied and the gift
is missing, the cart answers with a suggestion, the buyer's form adds the gift
as a visible, removable line, and the engine then discounts it.

`percent` is above 0 and at most 100; dinars are whole numbers. The issue
codes you can get in `errors[].code`, besides those of every offer
(`REQUIRED`, `INVALID_TYPE`, `INVALID_VALUE`, `TOO_LARGE`, …):

| Code | Means |
| - | - |
| `NOT_DECLARED` | `config.typeHandle` is not one of the `[[offers.types]]` of your installation's version |
| `UNKNOWN_FIELD` | A key the rule does not have (the rule is strict) |
| `EMPTY` | A leaf with no key |
| `TOO_DEEP` | `all` / `any` nested more than 3 deep |
| `DUPLICATE` | The same action key twice |
| `NO_ACTION` | Only a `label`: nothing to price |
| `INVALID` | A condition or an action that matches none of the shapes above |
| `ACTION_CLASS_MISMATCH` | An action that belongs to another class than the rule's |
| `ONE_OF_PRODUCT_OR_VARIANT` | `give.item` names both a product and a variant, or neither |

## Errors these routes add

Beyond the codes every route shares ([Errors](/guides/errors)):

| Code | Status | When |
| - | - | - |
| `OFFER_NOT_OWNED` | 403 | The offer is the merchant's or another app's (writes, codes, redemptions) |
| `OFFER_INVALID` | 400 | The offer does not pass the dashboard's validation: `errors` lists `{ field, code }` |
| `OFFER_KIND_NOT_AVAILABLE`, `OFFER_KIND_IMMUTABLE` | 400 | A kind not offered; a changed `kind` or `method` |
| `OFFER_TARGET_NOT_FOUND`, `OFFER_TARGET_OUTSIDE_STORE` | 400 | A target (or a product the rule names) that does not exist, or belongs to another store |
| `OFFER_CODE_INVALID` | 400 | A single code that is not 3 to 30 letters, digits, `-` or `_` |
| `OFFER_STORE_NOT_FOUND`, `OFFER_CODE_NOT_FOUND` | 404 | `storeId` is not a store of the business; `codeId` is not a code of this offer |
| `OFFER_VERSION_CONFLICT` | 409 | `expectedVersion` is stale: `currentVersion` says what it is |
| `OFFER_ARCHIVED`, `OFFER_NOT_PUBLISHED`, `OFFER_ENDED`, `OFFER_NOT_CODE_METHOD`, `OFFER_CODE_TAKEN` | 409 | The offer's state, or the code's uniqueness, does not allow the move |
| `PLAN_LIMIT_REACHED` | 403 | The plan's limit on live offers (publish, resume, an edit that makes the offer count) |
| `STORE_SCOPE_FORBIDDEN` | 460 | A store outside the installation's |

`OFFER_APP_OWNED` (409) is not one of these: it is what the **merchant's
dashboard** answers when someone tries to edit or duplicate an app-owned
offer, as described above. Your own calls never get it.


# @tassyir/app
Source: https://developers.tassyir.io/packages/app

Server SDK for Tassyir apps: token exchange and refresh, ID-token and webhook verification, and a typed Admin API client.

The server side of a [Tassyir](https://tassyir.io) app. It gets and refreshes
an installation's tokens, verifies the ID tokens the dashboard hands your
embedded page and the webhooks Tassyir sends, and calls the Admin API through
a client typed from its OpenAPI document (version `2026-10`).

It has no runtime dependency and uses only `fetch` and WebCrypto, so it runs
on Node 22 or later and on Workers-like runtimes (Cloudflare Workers, Deno,
Bun). It ships ESM and CommonJS.

## Install

```bash theme={null}
npm install @tassyir/app
```

## Example

An Express server for an app with an embedded page and webhooks. Tokens and
the refresh lock live in Redis ([ioredis](https://github.com/redis/ioredis)).
Secrets come from the environment, never from code.

```ts theme={null}
import express from 'express';
import { Redis } from 'ioredis';
import {
  createTassyirApp,
  isTassyirError,
  TassyirVerificationError,
  type RefreshLock,
  type TokenSet,
  type TokenStore,
  type WebhookEvent,
} from '@tassyir/app';

const redis = new Redis(process.env.REDIS_URL!);

// Where each installation's offline tokens live. Encrypt them at rest in a
// real deployment: they are secrets.
const tokenStore: TokenStore = {
  async get(installationId) {
    const value = await redis.get(`tassyir:tokens:${installationId}`);
    return value ? (JSON.parse(value) as TokenSet) : undefined;
  },
  async set(installationId, tokens) {
    await redis.set(`tassyir:tokens:${installationId}`, JSON.stringify(tokens));
  },
  async delete(installationId) {
    await redis.del(`tassyir:tokens:${installationId}`);
  },
};

// One refresh at a time per installation, across every process.
const refreshLock: RefreshLock = {
  async withLock(key, task) {
    const owner = crypto.randomUUID();
    for (
      let tries = 0;
      !(await redis.set(key, owner, 'PX', 60_000, 'NX'));
      tries += 1
    ) {
      if (tries === 120) throw new Error(`Timed out waiting for ${key}`);
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
    try {
      return await task();
    } finally {
      await redis.eval(
        "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) end return 0",
        1,
        key,
        owner,
      );
    }
  },
};

const tassyir = createTassyirApp({
  clientId: process.env.TASSYIR_CLIENT_ID!, // app_…
  clientSecret: process.env.TASSYIR_CLIENT_SECRET!, // tsy_cs_…
  appId: process.env.TASSYIR_APP_ID!, // the numeric app id from the developer console
  tokenStore,
  refreshLock,
  retries: 3,
});

// Installations are recorded from app/installed. A delivery can arrive before
// it (no ordering): refusing it is fine, Tassyir retries it.
const isOurInstallation = async (id: string, event: WebhookEvent) =>
  event.type === 'app/installed' ||
  (await redis.sismember('tassyir:installations', id)) === 1;

const app = express();

// Webhooks: verify the RAW body, answer within 10 seconds, work afterwards.
app.post(
  '/webhooks',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    let delivery;
    try {
      delivery = await tassyir.verifyWebhook(
        { headers: req.headers, body: req.body as Buffer },
        { installationId: isOurInstallation },
      );
    } catch (error) {
      if (isTassyirError(error, 'WEBHOOK_TEST_DELIVERY'))
        return res.sendStatus(200);
      if (error instanceof TassyirVerificationError) return res.sendStatus(400);
      throw error;
    }
    // At least once, in any order: skip a webhook-id you already handled.
    if (
      !(await redis.set(
        `tassyir:seen:${delivery.id}`,
        '1',
        'EX',
        259_200,
        'NX',
      ))
    ) {
      return res.sendStatus(200);
    }
    res.sendStatus(200);

    switch (delivery.event.type) {
      case 'app/installed':
        await redis.sadd('tassyir:installations', delivery.installationId);
        break;
      case 'orders/created':
        console.log(
          'new order',
          delivery.event.data.order.orderNumber,
          delivery.event.data.order.total,
        ); // total: "2500.00"
        break;
      case 'app/uninstalled':
        await redis.srem('tassyir:installations', delivery.installationId);
        await tassyir.tokens.forget(delivery.installationId);
        break;
    }
  },
);

// The embedded page calls this with its App Bridge ID token as a bearer.
app.get('/api/pending-orders', async (req, res) => {
  const idToken = req.get('authorization')?.replace(/^Bearer /, '') ?? '';
  try {
    const { idToken: session } = await tassyir.authenticate(idToken);
    const admin = tassyir.admin(session.installationId);
    const orders = [];
    for await (const order of admin.paginate('/orders', {
      query: {
        status: 'pending',
        limit: 100,
        fields: ['orderNumber', 'total', 'createdAt'],
      },
    })) {
      orders.push(order);
      if (orders.length === 200) break;
    }
    res.json(orders);
  } catch (error) {
    if (error instanceof TassyirVerificationError) return res.sendStatus(401);
    throw error;
  }
});

app.listen(3000);
```

A headless app (no embedded page) gets its first tokens from the install code
that its `auth.callback_url` receives:

```ts theme={null}
app.get('/auth/callback', async (req, res) => {
  const tokens = await tassyir.redeemInstallCode(String(req.query.code)); // stored for you
  res.send(`Installed on business ${tokens.businessId}`);
});
```

## Tokens

* `tassyir.authenticate(idToken)` verifies the ID token, then reuses the
  installation's stored **offline** token, or exchanges the ID token for one
  and stores it. Keep that token: each exchange starts a new refresh family,
  and Tassyir keeps at most 25 per installation. With `{ tokenType: 'online' }`
  it exchanges for a one-hour token that acts for the dashboard user; that
  token is not stored and has no refresh token.
* `tassyir.redeemInstallCode(code)` redeems a `tsy_ic_…` code (5 minutes, one
  use) and stores the tokens.
* `tassyir.oauth` is the raw token endpoint client (`exchangeIdToken`,
  `redeemInstallCode`, `refresh`), with HTTP Basic client authentication.
  Every refusal is a `TassyirOAuthError`: `error` is OAuth's code
  (`invalid_grant`, …), `code` is `OAUTH_INVALID_GRANT`, and `fix` says what
  to do.
* `TokenStore` is yours to implement (`get`, `set`, `delete` by installation
  id). `set` must be durable when it resolves, and `get` must return the
  latest `set`. `MemoryTokenStore` is for tests.

### Refresh locking

A refresh rotates the refresh token. If the old token is presented again
more than 60 seconds later, Tassyir revokes every token of the installation,
and the merchant has to re-open or reinstall the app. `TokenManager`
(`tassyir.tokens`) is built so that this does not happen:

* At most one refresh runs per installation in a process. Concurrent callers
  wait for it and get its result.
* `refreshLock` serialises refreshes across processes. The token set is read
  again inside the lock, so a process that waited picks up the fresh token
  instead of presenting the spent one.
* The rotated set is written to the store before the new access token is
  used. If that write fails, the call throws `TOKEN_STORE_FAILED`. The process
  keeps the set in memory and writes it again on the next call.
* A refresh whose answer was lost is retried with the same token, for at most
  40 seconds. That is inside the 60-second grace, so the retry is safe.
* The process never presents a refresh token it has already rotated
  (`REFRESH_TOKEN_ALREADY_USED`), even if a stale store hands it back.
* A refresh token that Tassyir refuses is removed from the store. The next
  `authenticate` then exchanges again.

Without `refreshLock`, two processes can still refresh the same installation
at the same moment. Inside the grace window that is harmless, but use a lock
once you run more than one process.

## ID tokens

`tassyir.verifyIdToken(token)` (or `verifyIdToken(token, { clientId, keys })`)
checks the token the way the backend does:

* `alg: EdDSA` only. The key is chosen by `kid` from
  `GET /apps/.well-known/jwks.json`, which is cached for an hour and fetched
  again on an unknown `kid` (at most once every 30 seconds).
* The signature is checked before any claim is read.
* `iss` must be `https://api.tassyir.io/apps` and `aud` your client id.
* `exp`, `nbf` and `iat` allow the backend's 30 seconds of leeway, and a
  token may live at most 60 seconds.

It returns the user, business, installation, session and locale. An ID token
is a bearer credential for about a minute: accept it over HTTPS only.

## Webhooks

`tassyir.verifyWebhook({ headers, body }, { installationId })` (or
`verifyWebhook`, or `verifyWebhookRequest(request, …)` for a Fetch `Request`)
checks a delivery in this order:

1. The `v1a` Ed25519 signature over `{webhook-id}.{webhook-timestamp}.{body}`,
   on the **raw** body bytes. During a key rotation a delivery carries several
   signatures, and any one that verifies is enough. Keys come from
   `GET /apps/webhook-keys` and are fetched again when no key verifies.
2. The timestamp, within 5 minutes of now.
3. The envelope's `appId` (yours) and `installationId` (your check: an id, a
   list, or a function).
4. The unsigned `tassyir-*` headers must agree with the signed envelope.

If the keys cannot be fetched once the cached copy has expired, verification
throws `KEYS_UNAVAILABLE`: answer 503 and Tassyir retries the delivery later.

Test deliveries from the developer console carry sample data. They are
refused with `WEBHOOK_TEST_DELIVERY` unless you pass
`{ testDeliveries: 'accept' }`. The SDK recognises them by their signed
`dlv_test_…` id and `evt_0` envelope id, not only by the `tassyir-test`
header.

`delivery.event` is typed per topic: `switch (delivery.event.type)` narrows
`data`.

## App proxy

Not live yet: the app proxy opens after the marketplace. A buyer's request
to `https://<store>/apps/<handle>/<rest>` reaches your server at
`<hosting.url><[app_proxy] path>/<rest>`, forwarded by Tassyir without the
buyer's cookies or IP, with `tassyir-*` headers and an Ed25519 `v1a`
signature by Tassyir's webhook keys over
`tassyir-proxy.v1.{timestamp}.{METHOD}.{path+query}.{sha256 hex of the body}.{installationId}.{storeId}`.
`verifyProxyRequest(request, { keys, installationId })` (or `verifyProxy`
with `{ method, url, headers, body }`) checks it:

```ts theme={null}
import { verifyProxyRequest, WebhookKeys } from '@tassyir/app';

const keys = WebhookKeys.remote(); // one per process: it caches

export async function proxy(request: Request): Promise<Response> {
  let verified;
  try {
    verified = await verifyProxyRequest(request, {
      keys,
      installationId: (id) => installations.has(id),
    });
  } catch {
    return new Response(null, { status: 401 });
  }
  const reviews = await reviewsFor(verified.installationId, verified.storeId);
  return Response.json(reviews);
}
```

1. The signature, on the path and query exactly as received and the raw
   body. The label keeps a webhook's signature from passing as a proxy
   request, and the reverse.
2. The timestamp, within 5 minutes of now (`PROXY_TIMESTAMP_OUT_OF_RANGE`).
3. The installation, by your check (an id, a list, or a function given the
   installation and the store). Required: the keys are Tassyir's, the same
   for every app, so this check is what makes a request yours.

It answers the signed `installationId`, `storeId`, `method` and `path`, and
the headers the signature does not cover (`businessId`, `storeHost`,
`country`, `locale`) under `unsigned`. Refusals are
`TassyirVerificationError`s with a `PROXY_*` code: answer 401. A request may
be replayed within the 5 minutes, so keep non-GET handlers idempotent. The
store answers only JSON, plain text, XML or images from the proxy, and drops
`Set-Cookie`. How a hosted app receives proxy requests is settled when the proxy opens.

## Admin API

`tassyir.admin(installationId)` returns an `AdminClient` that uses the
installation's stored token and refreshes it as needed. To call with a token
you hold (an online token, say), use `tassyir.adminWithToken(tokens)` or
`new AdminClient({ accessToken })`. Paths are relative to `/apps/2026-10`, and
paths, parameters, bodies and answers are typed from the OpenAPI document:

```ts theme={null}
const { data: order } = await admin.get('/orders/{id}', { path: { id } });
await admin.post('/orders/{id}/confirm', {
  path: { id },
  idempotencyKey: `confirm-${id}`,
});
const created = await admin.request('post', '/orders', { body }); // created.status: 201, or 200 for a duplicate
```

* **Errors.** A problem+json answer becomes a `TassyirApiError` with `code`,
  `fix`, `requestId`, `status`, `retryAfterSeconds`, `rateLimit` and the whole
  `problem`. `AdminApiErrorCode<'post', '/orders/{id}/confirm'>` lists the
  codes that call can answer.
* **Idempotency.** Every write sends an `Idempotency-Key`: a new UUID per call
  by default, reused by the SDK's own retries. You can pass your own key, or
  `false` to send none.
* **Rate limits.** Every answer's `RateLimit-*` headers reach `onResponse` and
  `ApiResponse.rateLimit`.
* **Retries** are off by default; turn them on with `retries: 3`. When on, the
  SDK waits `Retry-After` and retries, writes included, 429 `RATE_LIMITED`
  (the installation's bucket), 429 `BUSINESS_RATE_LIMITED` (the ceiling all
  the business's apps share), 429 `BULK_EXPORT_RATE_LIMITED` (5 bulk exports
  per business an hour) and 503 `API_BUSY` (the API was too busy and did
  nothing); a `Retry-After` longer than `maxDelayMs` (30 s by default) throws
  at once. It retries 409 `IDEMPOTENCY_KEY_IN_USE`, and any other 503,
  network errors, 502 and 504 for requests that are safe to repeat (reads,
  and writes with a key). It retries 500 only for reads. A 401
  `APP_TOKEN_INVALID` gets a new token and one more try. It never retries
  429 `IMAGE_QUOTA_REACHED` (`POST /images`): a daily quota is not worth
  retrying, so it throws at once and the error's `problem` says which quota
  is full (`per`, `window`: `day` or `minute`, `limit`, `retryAfter`), for
  the app to wait or stop. It also never retries 503
  `BULK_EXPORTS_NOT_CONFIGURED` (exports are off on that Tassyir environment)
  or 409 `BULK_EXPORT_IN_PROGRESS` (wait for `bulk/finished`, or read
  `GET /bulk/exports/{id}`).
* **Pagination.** `admin.paginate(path, { query })` walks the keyset cursors
  and yields items.
* **`fields`** takes a list of field names, typed per resource:
  `fields: ['status', 'total']`.
* **Money** stays a decimal string (`"2500.00"`). JSON is parsed as it is
  received; use a decimal library for arithmetic, never `parseFloat`.

## Errors

Everything the SDK throws is a `TassyirError`. It has a stable `code` to act
on, a `message` for people, and a one-sentence `fix`. The subclasses are
`TassyirVerificationError`, `TassyirOAuthError`, `TassyirApiError` and
`TassyirTokenError`. No error message contains a token or a secret.

## Runtimes

Ed25519 verification uses WebCrypto (`crypto.subtle`, algorithm `Ed25519`).
That needs no dependency, and the same code runs on Node 22, Cloudflare
Workers, Deno and Bun, so this package does not use `node:crypto` or `jose`.
The test suite checks the built bundle against tokens and deliveries signed
by the Tassyir backend itself. Inject `fetch` to add a proxy, logging or a
test double.

## Tassyir Hosting

An app on Tassyir Hosting is a Cloudflare Worker that Tassyir runs for each
installation, inside the merchant's dashboard. It holds no client secret and
no token. Its capabilities arrive with each request in **`ctx.props`**,
never in `env` (one script serves every installation pinned to its version):

| `ctx.props` | What it is |
| - | - |
| `installation` | `{ id, businessId, appId, handle, version, scopes, storeAccess, storeIds, devStore }`: the installation this request runs for. |
| `viewer` | `{ userId, sessionId }`: the dashboard member who opened the page, or `null` when nobody is looking (a webhook delivery). Who is looking, not a permission. |
| `STORAGE` | The installation's own SQLite database: `sql(query, ...bindings)`, `batch([...])` (one transaction), `usage()`. Erased 48 hours after an uninstall. |
| `TASSYIR` | The Admin API as the installation: `fetch()` with the Admin API's URLs, no token. |

```ts theme={null}
import {
  hostedAdmin,
  isTassyirError,
  readHostedProps,
  verifyHostedWebhook,
} from '@tassyir/app';

export default {
  async fetch(request: Request, env: unknown, ctx: { props?: unknown }) {
    // Checked: throws HOSTED_PROPS_MISSING anywhere but Tassyir Hosting.
    const props = readHostedProps(ctx);
    const url = new URL(request.url);

    if (request.method === 'POST' && url.pathname === '/webhooks') {
      try {
        const delivery = await verifyHostedWebhook(request, props);
        // Deduplicate on delivery.id, then handle delivery.event.
        console.info(delivery.topic);
        return new Response(null, { status: 200 });
      } catch (error) {
        // The keys could not be read: Tassyir delivers it again later.
        if (isTassyirError(error, 'KEYS_UNAVAILABLE')) {
          return new Response(null, { status: 503 });
        }
        if (isTassyirError(error)) return new Response(null, { status: 400 });
        throw error;
      }
    }

    if (url.pathname === '/api/orders') {
      // The typed client, its requests sent through ctx.props.TASSYIR.
      const admin = hostedAdmin(props);
      const page = await admin.get('/orders', {
        query: { status: 'pending', limit: 20 },
      });
      const { rows } = await props.STORAGE.sql(
        'SELECT value FROM settings WHERE key = ?',
        'highlightFrom',
      );
      return Response.json({ orders: page.data, settings: rows[0] ?? null });
    }
    return new Response('Not found', { status: 404 });
  },
};
```

* **`readHostedProps(ctx)`** returns `ctx.props` typed (`HostedProps`) after
  checking its shape, or throws `HOSTED_PROPS_MISSING` with a fix (the Worker
  runs outside Tassyir Hosting, or a test forgot its stand-ins).

* **`hostedAdmin(props, { retries, timeoutMs, onResponse })`** is the same
  `AdminClient` as above, its requests sent through `ctx.props.TASSYIR` with
  no `Authorization` header. Each call is a subrequest of the invocation
  (Tassyir Hosting allows 50 by default), retries included. Answers and
  problem+json refusals are the API's. The binding refuses some requests
  itself, in the same problem shape (`HOSTED_BINDING_ERRORS`, with no
  `requestId`):

  * `HOSTED_PATH_NOT_ALLOWED` (400): only Admin API paths (`/apps/<version>/…`);
  * `RESPONSE_TOO_LARGE` (502): an answer over 8 MiB, never retried (ask for
    less: a smaller `limit`, `fields`);
  * `TASSYIR_BINDING_NOT_AVAILABLE` (503): the binding is not configured,
    never retried;
  * `METHOD_NOT_ALLOWED`, `BAD_REQUEST`, `IDEMPOTENCY_KEY_INVALID`,
    `PAYLOAD_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE` and `SERVICE_UNAVAILABLE`
    (the API did not answer within 30 seconds; retried like any 503).

  A call the API refuses for the installation's state (uninstalled, suspended,
  its version no longer released) is 401 `HOSTED_CALL_REFUSED`; it is never
  retried. Send ids as strings in bodies: the binding re-serialises the JSON,
  so a number past 2^53 would be rounded.

* **`verifyHostedWebhook(request, props, { keys?, testDeliveries? })`**
  checks a delivery to the manifest's webhook path. The API sends a hosted
  app's deliveries (the same headers, `v1a` signature and body as an external
  app's) through Tassyir Hosting, which runs the installation's version with
  `viewer: null` and POSTs the delivery to the app. The check is
  `verifyWebhook`'s, every rule of it: the signature, verified with Tassyir's
  published keys (`hostedWebhookKeys(props)`, below), the timestamp, test
  deliveries, the `tassyir-*` headers, the envelope naming this
  installation, its business and its app (taken from `ctx.props`). It also
  refuses a request with a viewer (`WEBHOOK_NOT_A_DELIVERY`: a page of the
  app). It never skips the signature: when the keys cannot be read it throws
  `KEYS_UNAVAILABLE` (or `KEYS_NOT_CONFIGURED`), which you answer with a 503,
  and Tassyir delivers again later. `app/uninstalled` and `business/redact`
  still arrive after an uninstall; during those two `TASSYIR` answers
  `HOSTED_CALL_REFUSED` (the key documents excepted).

* **`hostedWebhookKeys(props)`** is Tassyir's webhook keys as a hosted app
  reads them: `GET /apps/webhook-keys` through `ctx.props.TASSYIR` (a hosted
  Worker's own `fetch()` never reaches a Tassyir host). Make it per request,
  from that request's `ctx.props`, never in a module variable: the binding
  belongs to its request. Where Tassyir Hosting does not serve the key
  documents through the binding yet, it refuses the path, and deliveries
  answer `KEYS_UNAVAILABLE` until it does.

* **Shared isolates.** One isolate may serve several merchants: keep
  per-request state per request, never in a module variable.

## Updating the API types

The OpenAPI document is vendored in `openapi/` at a recorded backend commit.
With a clone of `tassyir/backend` in `TASSYIR_BACKEND_DIR`, run
`npm run openapi:check -w @tassyir/app` to compare it with the backend, and
`npm run openapi:update -w @tassyir/app` to vendor the new file and
regenerate the types. `npm run vectors:generate -w @tassyir/app` re-signs the
cross-check fixtures with the backend's own code.


# @tassyir/app-bridge
Source: https://developers.tassyir.io/packages/app-bridge

App Bridge for Tassyir apps: the embedded page's side of the dashboard bridge (ID tokens, toasts, modals, navigation, save bar, title bar, resource pickers, context), with React bindings.

App Bridge lets your app's page talk to the [Tassyir](https://tassyir.io)
dashboard. The page runs inside the dashboard's frame. With this package it
can get ID tokens, show toasts and modals, use the save bar and title bar,
navigate, pick products, collections or customers, and follow the dashboard's
language, direction and theme.

It runs in the browser only. It is ESM only, has no runtime dependency, and
works with any framework or none; `@tassyir/app-bridge/react` adds a provider
and hooks for React. It collects no analytics and uses no browser storage.

## Install

```bash theme={null}
npm install @tassyir/app-bridge
```

## Example

The whole loop: the page asks the bridge for an ID token, sends it to your
server, and your server verifies it with [`@tassyir/app`](https://github.com/tassyir/apps-sdk/tree/main/packages/app) before it
calls the Admin API.

The page (your manifest's `admin.page`):

```ts theme={null}
import { createAppBridge, isAppBridgeError } from '@tassyir/app-bridge';

// Create it once, as early as the page loads: its first message tells the
// dashboard the page is up.
const bridge = createAppBridge();

// Each request to your server carries a NEW ID token. Never keep one: it
// lives 60 seconds and the token endpoint accepts it once.
async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  const { token } = await bridge.idToken();
  const headers = new Headers(init.headers);
  headers.set('Authorization', `Bearer ${token}`);
  const response = await fetch(path, { ...init, headers });
  if (!response.ok) throw new Error(`${path} answered ${response.status}`);
  return (await response.json()) as T;
}

// The frame cannot see the dashboard's language, direction or theme.
bridge.on('context.changed', ({ locale, dir, theme }) => {
  document.documentElement.lang = locale;
  document.documentElement.dir = dir;
  document.documentElement.dataset['theme'] = theme;
});

await bridge.titleBar.set({ title: 'Pending orders' });
const orders = await api<{ orderNumber: string; total: string }[]>(
  '/api/pending-orders',
);
document.querySelector('#count')!.textContent = String(orders.length);

document.querySelector('#feature')!.addEventListener('click', async () => {
  try {
    const { selection } = await bridge.resource.pick({
      type: 'product',
      multiple: true,
    });
    if (selection.length === 0) return; // the merchant cancelled
    await api('/api/featured', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(selection.map((product) => product.id)),
    });
    await bridge.toast.show({
      message: `${selection.length} products featured`,
      tone: 'success',
    });
  } catch (error) {
    if (!isAppBridgeError(error)) throw error;
    // error.code is stable; error.fix says what to do about it.
    await bridge.toast.show({ message: error.message, tone: 'error' });
  }
});
```

Your server (here a Fetch handler; the [`@tassyir/app` README](https://github.com/tassyir/apps-sdk/tree/main/packages/app#example)
has the Express version with a token store):

```ts theme={null}
import { createTassyirApp, TassyirVerificationError } from '@tassyir/app';

const tassyir = createTassyirApp({
  clientId: process.env.TASSYIR_CLIENT_ID!, // app_…
  clientSecret: process.env.TASSYIR_CLIENT_SECRET!, // tsy_cs_…
});

export async function pendingOrders(request: Request): Promise<Response> {
  const idToken =
    request.headers.get('authorization')?.replace(/^Bearer /, '') ?? '';
  try {
    // Verifies the token (signature, your client id, 60 seconds), then reuses
    // the installation's stored offline token or exchanges this ID token for one.
    const session = await tassyir.authenticate(idToken);
    const admin = tassyir.admin(session.idToken.installationId);
    const { data } = await admin.get('/orders', {
      query: { status: 'pending', limit: 50, fields: ['orderNumber', 'total'] },
    });
    return Response.json(data);
  } catch (error) {
    if (error instanceof TassyirVerificationError) {
      return new Response(null, { status: 401 });
    }
    throw error;
  }
}
```

To know who is looking without calling the API, verify only:
`const who = await tassyir.verifyIdToken(idToken)` gives `userId`,
`businessId`, `installationId`, `sessionId` and `locale`.

## Who is looking

**Only the ID token says who is looking.** The dashboard loads your page at
`admin.page`, plus the app path and the dashboard's own query string. Tassyir
vouches for nothing in that address. Never read a business, a user or a store
from it to decide what to show or allow. `context` is for display only. To
learn who is looking, send `idToken()`'s token to your server and verify it
there with `@tassyir/app` (`verifyIdToken`, or `authenticate` to also get an
Admin API token). A token that has not been verified proves nothing.

The dashboard never sends your page a Tassyir credential. The ID token is the
only one, it is minted for your app and this installation, and it expires
after 60 seconds.

## Calls

Every call posts one message to the dashboard. It resolves with the payload
of the dashboard's reply, or rejects with an `AppBridgeError`. Payloads are
the ones the Tassyir App Bridge protocol defines. The SDK checks them before
posting, so most mistakes are refused without a round trip.

| Call | Resolves with | Refusals besides `INVALID_PAYLOAD`, `RATE_LIMITED` |
| - | - | - |
| `idToken()` | `{ token }` | `ID_TOKEN_UNAVAILABLE`, `APP_UNAVAILABLE`, `PERMISSION_DENIED`, `FAILED` |
| `toast.show({ message, tone? })` | nothing | |
| `modal.open({ path, title?, size? })` | `{ closedBy: 'app' \| 'merchant' }` | `BUSY`, `INVALID_DESTINATION`, `NOT_ALLOWED_HERE` |
| `modal.close()` | nothing | `NO_MODAL` |
| `navigate({ path, replace? })` | nothing | `INVALID_DESTINATION`, `NOT_ALLOWED_HERE` |
| `navigate({ dashboard, id? })` | nothing | `INVALID_DESTINATION`, `NOT_ALLOWED_HERE` |
| `saveBar.show({ saving? })` | nothing | `NOT_ALLOWED_HERE` |
| `saveBar.hide()` | nothing | `NOT_ALLOWED_HERE` |
| `titleBar.set({ title })` | nothing | `NOT_ALLOWED_HERE` |
| `resource.pick({ type, multiple? })` | `{ selection }` | `SCOPE_REQUIRED`, `PERMISSION_DENIED`, `STORE_NOT_ALLOWED`, `NO_STORE`, `BUSY` |
| `context.get()` | the context | |

* **`idToken`** mints a new token on every call; the SDK never caches one.
  Send each token to your server once.
* **`toast.show`**: `tone` is `info` (default), `success` or `error`. The
  dashboard signs the toast with your app's name and shows `message` as text:
  control and bidi characters become spaces, white space is folded, and it is
  cut to 150 characters. More than 2,000 characters is refused.
* **`modal.open`** shows one of your pages (`path`, the app-path rules below)
  in a dashboard modal and resolves when the modal closes. `title` follows the
  toast rules and is cut to 80 characters; `""` is refused, `null` means none.
  `size` is `small`, `medium` (default) or `large`. The modal's page may call
  `idToken`, `toast.show`, `modal.close`, `resource.pick` and `context.get`
  only; anything else is `NOT_ALLOWED_HERE`.
* **App paths** (`navigate`, `modal.open`) are relative to `admin.page` and
  start with one `/`: `/reviews/2?tab=sent`. No scheme or host, no backslash,
  white space, control or bidi character, fragment, or `.`, `..` or empty
  segment (percent-encoded ones too). At most 1,024 characters before the
  `?`, 2,048 in all, and a query of at most 1,024 characters once written the
  way `URLSearchParams` writes it.
* **`navigate({ path })`** says your app moved to another of its pages. The
  frame is not reloaded (show the page yourself, for example with your
  router); the dashboard's address follows, as a new history entry or, with
  `replace: true`, in place.
* **`navigate({ dashboard })`** leaves your app: `home`, `orders`,
  `order` (with `id`), `customers`, `customer` (with `id`), `tracking`,
  `inventory`, `products` (the current store's) or `apps`.
* **`saveBar.show`** shows the dashboard's save bar, busy while `saving` is
  true. Its buttons send `saveBar.save` and `saveBar.discard`. It stays until
  `saveBar.hide`, and it does not stop the merchant from leaving the page.
* **`titleBar.set`** sets your page's title beside the app's name; `null` or
  `""` clears it.
* **`resource.pick`** opens the dashboard's picker for `product`,
  `collection` or `customer` and resolves when the merchant closes it:
  `selection` is empty when cancelled, one item unless `multiple`, 50 at most.
  Products are `{ id, name, image }`, collections `{ id, name }`, customers
  `{ id, provinceCode }`, plus `name` and `phone` only when the installation
  holds `read_customer_contact`. It needs `read_products` (products,
  collections) or `read_customers` (customers) in your manifest.

`modal.open` and `resource.pick` wait for the merchant as long as the dialog
stays open. Every other call times out after 10 seconds (`timeoutMs` per
bridge or per call), and any call takes an `AbortSignal` (`signal`).

## Events and context

```ts theme={null}
const stop = bridge.on('context.changed', (context) => {});
bridge.on('saveBar.save', () => {});
bridge.on('saveBar.discard', () => {});
stop();
```

The context is `{ locale: 'ar' | 'en', dir: 'rtl' | 'ltr', theme: 'light' |
'dark', storeId: string | null }`. `storeId` is the dashboard's current store,
or `null` when there is none or your installation is limited to other stores.
`bridge.context.current` holds the latest one (`null` until the dashboard has
sent it), and `context.changed` listeners hear real changes only.

## How the bridge talks to the dashboard

* Messages go to `https://app.tassyir.io` only, never `*`. A message is taken
  only when it comes from the page's parent window **and** from that origin.
  Replies are matched to calls by id.
* **Ready.** `createAppBridge()` says hello at once (a `context.get`), which
  is what makes the dashboard count the page as loaded, and it repeats it with
  a back-off until the dashboard answers: a message posted before the
  dashboard listens is lost. Calls made meanwhile wait and are sent in order
  once it answers.
* **Leaving the page.** On `pagehide` the bridge clears the title and hides the
  save bar (`titleBar.set({ title: null })`, `saveBar.hide()`), so neither
  outlives the page that set them. It does not when the page is kept in the
  back/forward cache, because the whole dashboard is kept with it.
* **Limits.** The dashboard counts calls per installation over a sliding
  minute and refuses more with `RATE_LIMITED`. Past 240 messages a minute it
  drops them without answering. The bridge counts what this page sends and
  refuses (`RATE_LIMITED`, `source: 'sdk'`) instead of posting what the
  dashboard would refuse or drop.

| Call | Per minute |
| - | - |
| `idToken` | 30 |
| `toast.show` | 20 |
| `modal.open` | 10 |
| `modal.close` | 30 |
| `navigate` | 30 |
| `saveBar.show` | 60 |
| `saveBar.hide` | 60 |
| `titleBar.set` | 60 |
| `resource.pick` | 10 |
| `context.get` | 60 |

A page that makes more than 30 requests a minute to your server cannot ask
for a token per request: batch the requests, or have your server open its own
short session once it has verified a token.

## Errors

Every refusal is an `AppBridgeError` with:

* `code`: stable; act on it, never on `message`;
* `call`: the call that failed;
* `source`: `dashboard` (the dashboard's reply) or `sdk` (refused or failed
  before an answer);
* `path`: the payload field at fault, for the SDK's own `INVALID_PAYLOAD`;
* `message` for people, and `fix`, one sentence saying what to do.

`isAppBridgeError(error, code?)` narrows an unknown error.

| Code | Source | Meaning |
| - | - | - |
| `INVALID_PAYLOAD` | both | The payload breaks the call's rules. |
| `RATE_LIMITED` | both | Over the call's limit for the minute. |
| `ID_TOKEN_UNAVAILABLE` | dashboard | Tassyir cannot sign ID tokens now; the dashboard tells the merchant. |
| `APP_UNAVAILABLE` | dashboard | The installation cannot be opened any more (uninstalled, suspended). |
| `PERMISSION_DENIED` | dashboard | The signed-in member may not do this. |
| `SCOPE_REQUIRED` | dashboard | The installation lacks the scope a pick needs. |
| `STORE_NOT_ALLOWED` | dashboard | The installation is limited to other stores than the current one. |
| `NO_STORE` | dashboard | A collection pick with no current store. |
| `BUSY` | dashboard | A modal or picker is already open. |
| `NO_MODAL` | dashboard | `modal.close` with no modal open. |
| `NOT_ALLOWED_HERE` | dashboard | A call the modal's page may not make. |
| `INVALID_DESTINATION` | dashboard | A place the dashboard cannot open now. |
| `FAILED` | both | Anything else (or a code this version does not know); try again. |
| `NOT_EMBEDDED` | sdk | The page is not inside a frame. |
| `TIMEOUT` | sdk | No answer in time. |
| `ABORTED` | sdk | The call's `signal` fired. |
| `DESTROYED` | sdk | `bridge.destroy()` was called. |
| `INVALID_REPLY` | sdk | The dashboard answered in a shape this version does not read. |
| `NOT_IN_BROWSER` | sdk (thrown) | `createAppBridge()` ran without a browser window (server rendering). |
| `INVALID_ARGUMENT` | sdk | A bad `dashboardOrigin`, `timeoutMs` or event name. |
| `NO_PROVIDER` | sdk (thrown) | A React hook ran outside `<AppBridgeProvider>`. |

## Options

```ts theme={null}
const bridge = createAppBridge({
  timeoutMs: 10_000, // default timeout of each call
  dashboardOrigin: 'http://localhost:3000', // a local or staging dashboard only
});
```

Leave `dashboardOrigin` unset in production. Set it only to run your page
inside a dashboard on your machine or on staging, and never from the page's
address. It must be an exact origin (https, or http on localhost); `*` is
refused.

`bridge.destroy()` stops listening and rejects waiting calls with
`DESTROYED`. `bridge.embedded` is false when the page is not in a frame (every
call then rejects `NOT_EMBEDDED`), and `bridge.connected` turns true once the
dashboard has answered.

## Size

About 7 kB gzipped once minified (17.7 kB minified, 32 kB as shipped). Half
of it is the error messages and fix sentences.

## React

`@tassyir/app-bridge/react` is the same bridge for React 18 or 19 (an
optional peer dependency: only this entry imports React). One provider at the
root of the page, then hooks. They add React state and nothing else: every
call is the bridge's own, with its checks, limits and `AppBridgeError`s.

```tsx theme={null}
import {
  AppBridgeProvider,
  useBridgeContext,
  useNavigate,
  useSaveBar,
  useTitleBar,
  useToast,
} from '@tassyir/app-bridge/react';
import { useState } from 'react';
import { createRoot } from 'react-dom/client';

function Settings() {
  const context = useBridgeContext(); // null until the dashboard sends it
  const toast = useToast();
  const navigate = useNavigate();
  const [saved, setSaved] = useState('5000.00');
  const [draft, setDraft] = useState(saved);
  const [saving, setSaving] = useState(false);

  useTitleBar(context?.locale === 'ar' ? 'الإعدادات' : 'Settings');
  // Shown while the draft differs, busy while saving: the bar is asked to
  // show or hide only when that changes, and hidden on unmount.
  useSaveBar({
    dirty: draft !== saved,
    saving,
    onSave: () => {
      setSaving(true);
      void fetch('/api/settings', { method: 'PUT', body: draft })
        .then(async () => {
          setSaved(draft);
          await toast({ message: 'Saved', tone: 'success' });
        })
        .finally(() => setSaving(false));
    },
    onDiscard: () => setDraft(saved),
  });

  return (
    <form>
      <input value={draft} onChange={(event) => setDraft(event.target.value)} />
      <button
        type="button"
        onClick={() => void navigate({ dashboard: 'orders' })}
      >
        Orders
      </button>
    </form>
  );
}

createRoot(document.querySelector('#app')!).render(
  <AppBridgeProvider>
    <Settings />
  </AppBridgeProvider>,
);
```

| Export | What it is |
| - | - |
| `<AppBridgeProvider>` | Creates the page's bridge when it mounts (in an effect) and destroys it when it unmounts; `bridge` uses one you made instead, `options` passes `createAppBridge`'s. |
| `useAppBridge()` | The bridge itself, for any call. `NO_PROVIDER` outside the provider. |
| `useBridgeContext()` | `{ locale, dir, theme, storeId }`, or `null` until the dashboard sends it; re-renders on every real change. |
| `useBridgeEvent(event, listener)` | Listens while mounted to `context.changed`, `saveBar.save` or `saveBar.discard`; the latest listener is called. |
| `useTitleBar(title)` | Sets the title whenever `title` changes (`null` clears it). Returns the last refusal, or `null`. |
| `useSaveBar({ dirty, saving, onSave, onDiscard })` | The save bar while `dirty` or `saving`, busy while `saving`, its buttons to `onSave` / `onDiscard`. Returns the last refusal, or `null`. |
| `useModal()` | `{ open, close, isOpen }`: `isOpen` from `open` until its modal closes. |
| `useResourcePicker()` | `{ pick, isPicking }`: `isPicking` from `pick` until the merchant closes the picker. |
| `useToast()`, `useNavigate()`, `useIdToken()` | `bridge.toast.show`, `bridge.navigate`, `bridge.idToken`, as stable functions. |

* **One provider per page**, at its root: the bridge's first message is what
  makes the dashboard count the page as loaded. To say hello before React
  renders, create the bridge yourself as the page loads and pass it:
  `<AppBridgeProvider bridge={createAppBridge()}>`.
* **Server rendering:** the provider renders `fallback` (default nothing)
  until its bridge exists, which is never on a server: the bridge needs the
  browser window.
* `useTitleBar` and `useSaveBar` call the dashboard from effects, so they
  hand back a refusal as state instead of throwing; the other hooks return
  the bridge's promises.

## Checking against the dashboard

`src/frontend-crosscheck.test.ts` runs the dashboard's own bridge host code
(`lib/apps/bridge-protocol.ts` in the private `tassyir/frontend` repository)
against what this package sends: the constants, about 24,000 payloads, and
every call end to end. CI cannot reach that repository, so it runs locally:

```bash theme={null}
TASSYIR_FRONTEND_DIR=../frontend npm run crosscheck -w @tassyir/app-bridge
```

It reads `origin/main` (or `TASSYIR_FRONTEND_REF`) with `git show`; run
`git -C ../frontend fetch origin` first.


# @tassyir/app-manifest
Source: https://developers.tassyir.io/packages/app-manifest

Schema and validator for tassyir.app.toml, the Tassyir app manifest: the normalised manifest or every error with a code, a path and a fix.

The schema and validator for `tassyir.app.toml`, the manifest of a
[Tassyir](https://tassyir.io) app (manifest v1, API version `2026-10`). Give it
the parsed manifest. It returns either the normalised manifest or every error
at once, each with a stable `code`, the `path` of the field, a `message` and a
one-sentence `fix`. The Tassyir API validates uploads with this same code, so a
manifest this package accepts is one the API accepts, with the same errors in
the same order.

It never throws, reads no file, clock or network, and runs in Node and in
browsers. ESM and CommonJS, named exports only.

## Install

```bash theme={null}
npm install @tassyir/app-manifest
```

## Example

Parse the TOML with any TOML 1.0 parser ([`smol-toml`](https://www.npmjs.com/package/smol-toml) here), then validate:

```ts theme={null}
import { readFileSync } from 'node:fs';
import { parse } from 'smol-toml';
import { validateManifest } from '@tassyir/app-manifest';

const result = validateManifest(
  parse(readFileSync('tassyir.app.toml', 'utf8')),
);

if (!result.ok) {
  for (const error of result.errors) {
    console.error(
      `${error.code} at ${error.path || '(document)'}: ${error.message} ${error.fix}`,
    );
  }
  process.exit(1);
}

console.log(result.manifest.access.scopes); // [ 'read_orders', 'read_products' ]
```

A hosted app (Tassyir Hosting):

```toml theme={null}
name        = "Review Requests"
handle      = "review-requests"
api_version = "2026-10"

[access]
scopes          = ["read_orders", "read_products"]
optional_scopes = ["read_customer_contact"]

[access.scope_reasons]
read_orders           = "Find delivered orders to ask for a review"
read_products         = "Show the product in the review request"
read_customer_contact = "Send the review request to the buyer's phone"

[hosting]
mode          = "tassyir"
allowed_hosts = ["graph.facebook.com", "*.googleapis.com"]

[admin]
page = "/"

[[webhooks]]
topics = ["orders/delivered", "app/uninstalled"]
uri    = "/webhooks"

[[data.definitions]]
owner      = "product"
key        = "rating"
type       = "json"
visibility = "storefront"
```

An app on your own server, headless, with its compliance webhooks on another
host:

```toml theme={null}
name        = "Sheets Sync"
handle      = "sheets-sync"
api_version = "2026-10"

[access]
scopes        = ["write_orders", "read_products"]
scope_reasons = { write_orders = "Create orders from the rows of your sheet", read_products = "Match sheet rows to your products" }

[hosting]
mode = "external"
url  = "https://sync.example.com/tassyir"

[auth]
callback_url = "https://sync.example.com/tassyir/callback"

[[webhooks]]
topics = ["orders/created", "products/updated"]
uri    = "/hooks"

[[webhooks]]
topics = ["customers/data_request", "customers/redact", "business/redact"]
uri    = "https://privacy.example.com/tassyir"
```

Both examples are validated by this package's tests, so they cannot drift from
the code.

## What you get back

```ts theme={null}
{ ok: true,  manifest: AppManifest }   // the normalised manifest
{ ok: false, errors: ManifestError[] } // every error at once
```

The **normalised manifest** is what the API stores for a version: the file's
keys in a fixed order (`name`, `handle`, `api_version`, `access`, `hosting`,
`auth`, `admin`, `webhooks`, `data`, `storefront`, `offers`, `app_proxy`); every
list present (empty when absent); `auth`, `admin`, `admin.actions`, `offers` and
`app_proxy` only when they hold a value; scopes, their reasons and each webhook's topics in
catalogue order, `allowed_hosts` and a block's `data` sorted; lists of tables in
file order; a storefront block's `target` (`"any"` when absent), `data` and
`settings` always present. Validating a normalised manifest returns it
unchanged.

An **error** looks like this:

```json theme={null}
{
  "code": "MANIFEST_TOPIC_SCOPE_MISSING",
  "path": "webhooks[0].topics[1]",
  "message": "\"products/updated\" carries data that needs the \"read_products\" scope, which the manifest does not request.",
  "fix": "Add \"read_products\" to `access.scopes` (or `access.optional_scopes`), or remove \"products/updated\"."
}
```

`path` is the field in the parsed file (`""` for the whole document). The list
is sorted by field (manifest order, then array index), then code, so the same
document always gives the same errors in the same order, whatever the order of
its keys. One error per field. At most 50 errors, then
`MANIFEST_TOO_MANY_ERRORS`. A code is never renamed or reused:

| Code | When |
| - | - |
| `MANIFEST_NOT_A_TABLE` | The document is not a table (an array, a string, null, a date, a Map). |
| `MANIFEST_NOT_DATA` | The document holds a cycle or a value JSON cannot carry. |
| `MANIFEST_TOO_LARGE` | Larger than 64 KB as JSON. Nothing else is checked. |
| `MANIFEST_TOO_MANY_ERRORS` | Last entry when more than 50 errors were found. |
| `MANIFEST_FIELD_REQUIRED` | A required field is missing (`hosting.url` for an external app, `hosting.allowed_hosts` for a hosted one, a select setting's `options`). |
| `MANIFEST_FIELD_UNKNOWN` | A key that is not a manifest field. The fix names the near key or lists the accepted ones. |
| `MANIFEST_FIELD_TYPE` | A value of the wrong type (a string where an array is expected, a TOML date). |
| `MANIFEST_FIELD_NOT_FOR_MODE` | `hosting.url`, `auth.callback_url` or an absolute webhook `uri` on a hosted app; `allowed_hosts` on external. |
| `MANIFEST_LIST_TOO_LONG` | A list over its limit. |
| `MANIFEST_LIST_EMPTY` | A webhook entry with no topic. |
| `MANIFEST_LIST_TOO_SHORT` | A list under its minimum (a select setting's `options`: 2). |
| `MANIFEST_VALUE_NOT_ALLOWED` | A value outside a fixed list (`hosting.mode`, a data definition's `owner`, `type`, `visibility`, a block's `target`, a setting's `type`, an admin action's `target`). |
| `MANIFEST_NAME_INVALID` | `name` empty, too long, on two lines, with an invisible character or surrounding spaces. |
| `MANIFEST_HANDLE_INVALID` | `handle` is not 3-40 lowercase letters and digits joined by single hyphens. |
| `MANIFEST_HANDLE_RESERVED` | `handle` is reserved by Tassyir (`www`, `api`, `tassyir`, `google-sheets`, …). |
| `MANIFEST_API_VERSION_UNSUPPORTED` | `api_version` is not a supported version. |
| `MANIFEST_SCOPE_UNKNOWN` | Not a scope. The fix names the near scope or lists them. |
| `MANIFEST_SCOPE_NOT_AVAILABLE` | A scope the platform does not offer to apps yet (none in this release). |
| `MANIFEST_SCOPE_DUPLICATE` | A scope listed twice in one list. |
| `MANIFEST_SCOPE_REQUIRED_AND_OPTIONAL` | A scope in both `scopes` and `optional_scopes`. |
| `MANIFEST_SCOPE_ALREADY_IMPLIED` | An optional scope a required one already implies. |
| `MANIFEST_SCOPE_NEEDS_ANOTHER` | A scope that opens nothing alone (`read_customer_contact` without `read_orders`). |
| `MANIFEST_SCOPE_REASON_MISSING` | A requested scope without a reason. |
| `MANIFEST_SCOPE_REASON_UNUSED` | A reason for a scope the manifest does not request, or for a name that is not a scope. |
| `MANIFEST_SCOPE_REASON_INVALID` | A reason too short, too long, on two lines or with an invisible character. |
| `MANIFEST_URL_INVALID` | An absolute URL breaks a URL rule (http, port, credentials, query, fragment, capitals, a bad path). |
| `MANIFEST_URL_HOST_NOT_ALLOWED` | Such a URL points at an IP address, a private name or a Tassyir domain. |
| `MANIFEST_PATH_INVALID` | `admin.page`, an admin action's `path`, a relative webhook `uri` or `app_proxy.path` breaks the path rules. |
| `MANIFEST_PATH_RESERVED` | A hosted app's page, action, webhook or proxy path is `/.tassyir` or below it, which Tassyir keeps on hosted origins. |
| `MANIFEST_HOST_INVALID` | An `allowed_hosts` entry is not a hostname (a URL, a port, a path, capitals, a misplaced wildcard). |
| `MANIFEST_HOST_NOT_ALLOWED` | An `allowed_hosts` entry is an IP address, a private name or a Tassyir domain. |
| `MANIFEST_HOST_DUPLICATE` | An `allowed_hosts` entry listed twice. |
| `MANIFEST_TOPIC_UNKNOWN` | Not a webhook topic. The fix names the near topic (`orders/create` → `orders/created`). |
| `MANIFEST_TOPIC_DUPLICATE` | A topic subscribed twice in the manifest. |
| `MANIFEST_TOPIC_SCOPE_MISSING` | A topic whose resource needs a scope the manifest does not request. |
| `MANIFEST_DATA_KEY_INVALID` | A data definition's `key` is not `[a-z][a-z0-9_]{0,63}`. |
| `MANIFEST_DATA_KEY_DUPLICATE` | Two data definitions with the same `owner` and `key`. |
| `MANIFEST_DATA_LABEL_INVALID` | One language of a data definition's `label` breaks the `name` text rules. |
| `MANIFEST_BLOCKS_NOT_AVAILABLE` | `[[storefront.blocks]]` while the platform does not offer them (it does in this release). |
| `MANIFEST_BLOCKS_SCOPE_MISSING` | Storefront blocks without `write_storefront`. |
| `MANIFEST_BLOCK_SCRIPT_NOT_ALLOWED` | A block key that would put code on the storefront (`script`, `js`, `html`, `src`, `on…`). |
| `MANIFEST_BLOCK_HANDLE_INVALID` | A block `handle` breaks the handle rules. |
| `MANIFEST_BLOCK_HANDLE_DUPLICATE` | Two blocks with the same handle. |
| `MANIFEST_BLOCK_TEMPLATE_INVALID` | A block `template` is not a lowercase relative `.liquid` path of the bundle. |
| `MANIFEST_BLOCK_STYLESHEET_INVALID` | A block `stylesheet` is not a lowercase relative `.css` path of the bundle. |
| `MANIFEST_BLOCK_NAME_INVALID` | One language of a block's `name` breaks the `name` text rules. |
| `MANIFEST_BLOCK_DATA_INVALID` | A block `data` entry is not `<owner>.<key>` with the owner `business`, `store` or `product`. |
| `MANIFEST_BLOCK_DATA_DUPLICATE` | A block lists the same data key twice. |
| `MANIFEST_BLOCK_DATA_NOT_DECLARED` | A block reads a key no `[[data.definitions]]` entry declares. |
| `MANIFEST_BLOCK_DATA_NOT_STOREFRONT` | A block reads a key declared without `storefront` visibility. |
| `MANIFEST_BLOCK_DATA_TARGET_MISMATCH` | A block reads product data but is not placed on the product page (`target = "product"`). |
| `MANIFEST_BLOCK_SETTING_KEY_INVALID` | A setting's `key` is not `[a-z][a-z0-9_]{0,39}`. |
| `MANIFEST_BLOCK_SETTING_KEY_DUPLICATE` | Two settings of one block with the same `key`. |
| `MANIFEST_BLOCK_SETTING_LABEL_INVALID` | One language of a setting's or an option's `label` breaks the `name` text rules. |
| `MANIFEST_BLOCK_SETTING_FIELD_NOT_FOR_TYPE` | `options` on a type other than `select`, `min` or `max` on a non-number, `max_length` on a non-text type. |
| `MANIFEST_BLOCK_SETTING_OPTION_INVALID` | An option's `value` is not 1-40 lowercase letters, digits, `_` and `-`. |
| `MANIFEST_BLOCK_SETTING_OPTION_DUPLICATE` | Two options of one select with the same `value`. |
| `MANIFEST_BLOCK_SETTING_RANGE_INVALID` | `min` above `max`, a non-whole bound on an integer, a non-finite number, `max_length` outside 1-1000. |
| `MANIFEST_BLOCK_SETTING_DEFAULT_INVALID` | A setting's `default` is not a value of its type (or the type takes none). |
| `MANIFEST_PROXY_NOT_AVAILABLE` | `[app_proxy]` while the platform does not forward to apps yet (this release). |
| `MANIFEST_PROXY_SCOPE_MISSING` | `[app_proxy]` without `write_storefront`. |
| `MANIFEST_ACTION_HANDLE_INVALID` | An admin action's `handle` breaks the handle rules. |
| `MANIFEST_ACTION_HANDLE_DUPLICATE` | Two admin actions with the same handle. |
| `MANIFEST_ACTION_LABEL_INVALID` | One language of an admin action's `label` breaks the `name` text rules. |
| `MANIFEST_ACTION_SCOPE_MISSING` | An admin action whose target needs a read scope the manifest does not request. |
| `MANIFEST_OFFER_TYPES_NOT_AVAILABLE` | `[[offers.types]]` against a vocabulary where `write_offers` is not offered. |
| `MANIFEST_OFFER_TYPES_SCOPE_MISSING` | `[[offers.types]]` without `write_offers` (in `scopes` or `optional_scopes`). |
| `MANIFEST_OFFER_TYPE_HANDLE_INVALID` | An offer type's `handle` is not `[a-z0-9][a-z0-9-]{0,39}`. |
| `MANIFEST_OFFER_TYPE_HANDLE_DUPLICATE` | Two offer types with the same handle. |
| `MANIFEST_OFFER_TYPE_LABEL_INVALID` | One language of an offer type's `label` (50 characters) or `description` (200) breaks the text rules. |

## API

| Export | What it does |
| - | - |
| `validateManifest(input, vocabulary?)` | Validates a parsed manifest. The vocabulary defaults to `MANIFEST_VOCABULARY`. |
| `validateManifestField('handle' \| 'name', value, path?)` | Checks one field with its manifest rule, code and fix (a form or a CLI prompt, before a manifest exists). |
| `manifestJsonSchema(vocabulary?, apiVersion?)` | The JSON Schema (draft 2020-12) of one API version, as an object. |
| `buildManifestSchema(vocabulary?, apiVersion?)` | The zod 4 schema the JSON Schema is generated from. |
| `manifestVersionColumns(manifest, vocabulary?)` | From a normalised manifest: `{ apiVersion, scopes, optionalScopes, webhookTopics, allowedHosts }`. |
| `resolveManifestUri(manifest, uri)` | The absolute URL of `admin.page` or a webhook `uri`, and whether Tassyir reaches it as `hosted` or `external`. |
| `hostedAppOrigin(handle)` | `https://{handle}.tassyir-apps.com`. |
| `formatManifestPath(segments)` | `['webhooks', 0, 'uri']` → `webhooks[0].uri`, as error paths are written. |
| `MANIFEST_VOCABULARY` | The API versions, scopes (with what each implies) and webhook topics (with the scope each needs) of this release. |
| `MANIFEST_ERROR_CODES`, `MANIFEST_LIMITS`, … | The error codes, the limits, the reserved handles, domains and hosted path prefix, and the fixed lists, as constants. |
| `SETTING_TYPES`, `BLOCK_TARGETS`, `ADMIN_ACTION_TARGETS`, … | The Phase 2 lists: setting types, block targets and data owners, admin action targets and the scope each needs. |

## Storefront blocks, the app proxy, admin actions and offer types

This release validates the marketplace's manifest fields. They are **not
live yet**: until the marketplace opens, a manifest that uses them passes here
and is refused on upload.

* `write_storefront` is requestable, and `[[storefront.blocks]]` takes
  `stylesheet`, `name` (`{ ar, en }`), `target` (`product` or `any`), `data`
  (the app data keys the template reads, `<owner>.<key>`, declared with
  `storefront` visibility) and `[[storefront.blocks.settings]]`;
* a setting is `key`, `type` (`SETTING_TYPES`: `string`, `text`, `boolean`,
  `integer`, `number`, `select`, `color`, `image`, `url`, `product`,
  `collection`), `label` (`{ ar, en }`) and, by type, `default`, `options`
  (`{ value, label }`, 2 to 20), `min` / `max`, `max_length`;
* `[[data.definitions]]` takes a `label` (`{ ar, en }`);
* `[[admin.actions]]`: `handle`, `target` (`ADMIN_ACTION_TARGETS`), `label`
  and `path`, at most 10;
* `[[offers.types]]` (at most 10) declares an offer type the merchant can
  create "from your apps": `handle` (`OFFER_TYPE_HANDLE_PATTERN`, unique),
  `class` (`OFFER_TYPE_CLASSES`: `product`, `order` or `delivery`), `path` (the
  app's page that configures one offer, at most 200 characters), `label` and an
  optional `description` (`{ ar, en }`). Declaring any needs the
  `write_offers` scope (`OFFER_TYPES_SCOPE`, which implies `read_offers`); the
  rule of each offer is written through the Admin API, not in the manifest;
* `[app_proxy]` (`path`) is part of the shape, refused until the platform
  forwards store requests to apps (`MANIFEST_PROXY_NOT_AVAILABLE`).

The developer guide has an example of each:
[The manifest](https://developers.tassyir.io/guides/manifest#marketplace-fields-not-live-yet).

## JSON Schema

The JSON Schema of each API version ships with the package:
`@tassyir/app-manifest/schemas/manifest.2026-10.schema.json`. It states the shape
(types, required and unknown fields, list sizes, patterns) for editors and
agents. The validator also checks the rules across fields and the precise URL
and hostname rules, so a document the schema accepts can still be refused. In
an editor that reads schema directives (Taplo, Even Better TOML), start
`tassyir.app.toml` with:

```toml theme={null}
#:schema ./node_modules/@tassyir/app-manifest/schemas/manifest.2026-10.schema.json
```

## The vocabulary, and keeping up with the API

`MANIFEST_VOCABULARY` is the data the validator checks against: supported API
versions, scopes and webhook topics. It equals what the Tassyir API builds from
its live catalogues, and the schema file is byte-for-byte the one the API
publishes. When the API adds a scope, a topic or an API version, a new release
of this package ships it; until you update, the validator refuses the new
names. The API itself passes its live vocabulary
(`validateManifest(input, vocabulary)`).

How the SDK repo proves that equality:
[docs/APP\_MANIFEST.md](https://github.com/tassyir/apps-sdk/blob/main/docs/APP_MANIFEST.md).

## License

MIT


# tassyir
Source: https://developers.tassyir.io/packages/cli

The Tassyir developer CLI: sign in, create apps, validate and deploy tassyir.app.toml, manage client secrets, dev stores and test webhooks. --json on every command.

The [Tassyir](https://tassyir.io) developer CLI. It signs you in from a
terminal, creates your apps, validates and deploys `tassyir.app.toml`,
manages client secrets, creates seeded dev stores and sends test webhooks.
For the marketplace, it previews storefront blocks, keeps your listing in a
file and submits the app to review.
Every command prints `--json`, and every refusal has a stable `code`, a
`message` and a one-sentence `fix`, so an AI coding agent can drive it as
well as you can.

An app runs on **your own server** (`hosting.mode = "external"`) or on
**Tassyir Hosting** (`hosting.mode = "tassyir"`), where `deploy` builds the
code, checks it by the API's rules before uploading it, and follows Tassyir's
scan of it to the verdict ([below](#tassyir-hosting)). The production API
keeps Tassyir Hosting switched off until hosted apps can be reached, and
answers a hosted deploy `APP_HOSTING_NOT_AVAILABLE`. `logs --tail` comes
later; its command already exists and says so.

## Install

Node 22.18 or later:

```bash theme={null}
npm install -g tassyir
```

Or run it without installing: `npx tassyir@latest <command>`.

## Example: from nothing to a test webhook

```bash theme={null}
tassyir login                       # approve the code in the dashboard
tassyir app init review-requests    # the starter (create-tassyir-app)
cd review-requests
npm install
npm run setup                       # .env with a new TOKEN_STORE_KEY
tassyir app create                  # handle and name from tassyir.app.toml
tassyir secrets create --write-env  # client id, secret and app id into .env
tassyir dev                         # the checklist: server, tunnel, hosting.url
tassyir deploy                      # validate, then upload as a new version
tassyir store create                # a dev store with products and orders
# install the app on the dev store from the developer console, then:
tassyir webhook trigger orders/created
```

The same with `--json`, as an agent would run it (the CLI prints each
document on one line; here they are spread out to read):

```bash theme={null}
tassyir deploy --json
```

```json theme={null}
{
  "ok": true,
  "app": { "id": "741…", "handle": "review-requests" },
  "unchanged": false,
  "version": {
    "version": 2,
    "current": true,
    "scopes": ["read_orders"],
    "webhookTopics": ["orders/created"],
    "…": "…"
  },
  "warnings": []
}
```

```bash theme={null}
tassyir deploy --json   # the same manifest again
```

```json theme={null}
{
  "ok": true,
  "app": { "id": "741…", "handle": "review-requests" },
  "unchanged": true,
  "version": { "version": 2 },
  "warnings": []
}
```

## Commands

| Command | What it does |
| - | - |
| `tassyir login` | Sign in: a one-time code to approve in the dashboard |
| `tassyir logout` | Revoke this machine's token on Tassyir, then forget it |
| `tassyir whoami` | Who you are signed in as, and the token's state |
| `tassyir app init [folder]` | Start an app in a new folder (`create-tassyir-app`) |
| `tassyir app create` | Create the app on Tassyir (handle and name from the manifest) |
| `tassyir app list` | Your apps |
| `tassyir validate [path]` | Check `tassyir.app.toml` with the API's own validator, offline |
| `tassyir deploy` | Validate the manifest, then upload it as the app's new version |
| `tassyir deploy --dry-run` | Every check `deploy` runs before it uploads; no sign-in |
| `tassyir block preview [handle]` | Render a storefront block with sample data, offline |
| `tassyir app version [n]` | One version (default the latest), a hosted one with its scan |
| `tassyir secrets list` | An app's client secrets (never the secrets) |
| `tassyir secrets create` | Mint the app's first client secret, shown once |
| `tassyir secrets rotate` | Mint a new one; the current ones keep working 24 hours |
| `tassyir secrets revoke <id>` | Revoke one secret now |
| `tassyir store create` | A dev store, seeded with products, orders and buyers |
| `tassyir store list` | Your dev stores |
| `tassyir webhook trigger <topic>` | A test event of one topic, sent to an installation's endpoint |
| `tassyir webhook deliveries` | The app's delivery log (30 days), with filters |
| `tassyir webhook replay <id>` | Send one delivery again, now |
| `tassyir listing pull` | Write the draft marketplace listing to `tassyir.listing.json` |
| `tassyir listing push` | Save that file as the draft listing; what is still missing |
| `tassyir submit` | Submit to the marketplace review, its checks followed |
| `tassyir submit --checks-only` | The review's checklist as a dry run; nothing submitted |
| `tassyir submissions [id]` | The app's reviews, or one with its checks and decision |
| `tassyir dev` | The checklist to run your app against a dev store |
| `tassyir logs --tail` | Not available yet: needs Tassyir Hosting |

`tassyir <command> --help` explains each one and its options.
`tassyir --help --json` is the whole catalogue as data. The commands that act
on an app take `--app <handle or id>`, and otherwise use the handle in
`./tassyir.app.toml`.

## Signing in

`tassyir login` uses the OAuth 2.0 Device Authorization Grant
([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)):

1. It asks Tassyir for a code and prints it with the approval page,
   `https://app.tassyir.io/{ar|en}/developers/cli?code=XXXX-XXXX`. In a
   terminal it offers to open the page (press Enter); it always prints the
   code, so you can check that the page shows the same one.
2. You approve on the page, signed in to the dashboard with developer mode
   on. Approve only a sign-in you started yourself.
3. Meanwhile the CLI asks every `interval` seconds (5), slowing down by 5
   seconds each time the API says `slow_down`. It stops on a denial, when the
   code expires (10 minutes), or when the API no longer knows the sign-in.

It then holds a **developer token** (`tsy_dt_…`). The token works on the
developer API only: it cannot read a business, place an order or approve
another sign-in. It lapses after 90 days without use and after 365 days in
any case, and stops working when you change your password. Signing in again
replaces this machine's token and revokes the old one. `tassyir logout`
revokes it on Tassyir (at once) and forgets it. Signing out of the dashboard
does not sign the CLI out.

The CLI never prints the token or the sign-in's device code, in any mode,
with `TASSYIR_DEBUG` too; as a last resort, anything shaped like one is
replaced by `tsy_dt_[redacted]` before it is printed. Control characters
in text from the API (escape sequences) are dropped the same way.

### Where the token is stored

| Order | Where | When |
| - | - | - |
| 1 | `TASSYIR_TOKEN` | Set it in CI to a token from a `tassyir login`. It is never stored, and `logout` never revokes it. |
| 2 | The OS keychain | macOS: the login keychain, through `/usr/bin/security`. Linux: the Secret Service (GNOME Keyring, KWallet), through `secret-tool`. |
| 3 | A file only you can read | `credentials.json` (mode 0600) in a folder only you can open (0700). |

Why this choice: a keychain keeps the token encrypted at rest and out of
backups and dotfile repositories, as `gh` does. The CLI talks to the
keychain through the programs the OS ships, so it needs no native module and
no install script; the token goes to them on stdin, never as an argument, so
no process listing shows it. When no keychain answers (a server without a
desktop session, a locked keychain, a container), the token goes to the
file, and `login` says so. On Windows the CLI uses the file, in
`%APPDATA%\tassyir`, a folder only your account can read: Credential Manager
has no command that gives a secret back without PowerShell, and that path is
not built yet.

`credentials.json` also holds what is not secret, per API origin: the email,
the user id and the token's id. So `whoami` can say who you are, and a
staging sign-in (`--api-origin`) sits next to production.

| Variable | Effect |
| - | - |
| `TASSYIR_TOKEN` | A developer token to use instead of the stored one (CI). |
| `TASSYIR_CREDENTIAL_STORE` | `keychain` (refuse when none answers) or `file`. Unset: the keychain, else the file. |
| `TASSYIR_CONFIG_DIR` | The folder of `credentials.json`. Default `$XDG_CONFIG_HOME/tassyir`, else `~/.config/tassyir` (`%APPDATA%\tassyir` on Windows). |
| `TASSYIR_API_ORIGIN` | Another Tassyir API (staging, a local one). https only; http only on `localhost`, `127.0.0.1` or `[::1]`. Same as `--api-origin`. |
| `TASSYIR_DEBUG` | `1` prints each request's method, path, status and duration on stderr. Never a header or a body. |

## Client secrets

A client secret (`tsy_cs_…`) is shown **once**: Tassyir keeps only its hash.

* `secrets create` mints the app's first secret and prints it with the client
  id and the app id. It refuses when the app already has a live secret:
  `secrets rotate` is the rotation, which gives the current secrets 24 more
  hours so a deployed server keeps working while you roll the new one out.
* With `--write-env` (or `--env-file <path>`), the three values go to `.env`
  and the secret is not printed. A value the file already holds is never
  replaced silently: the file is checked **before** the secret is minted, and
  only `--force` replaces it. The starter's placeholders
  (`app_your-client-id`, …) are filled in. A new file is created 0600; in a
  starter project, run `npm run setup` first (the CLI refuses otherwise,
  since setup never touches an existing `.env`). A folder that does not
  exist or cannot be written is refused before minting too.
* If writing `.env` still fails after the secret was minted, the error shows
  the three values once (`reveal` in `--json`): the secret is never lost.
* The CLI writes a secret nowhere else, ever.

## `--json`, errors and exit codes

With `--json`, a command prints one JSON document on one line on stdout:
`{"ok":true,…}`, or `{"ok":false,"error":{…}}`. `login` prints two lines:
first the code to approve (`"step":"authorize"`, `userCode`,
`verificationUriComplete`), then the result. A hosted `deploy` that waits
for its scan prints two too: first the uploaded version
(`"step":"uploaded"`, `next`), then the verdict. The result is always the
last line. Without `--json`, results go to stdout and refusals to stderr.

An error has a stable `code`, a `message` and a one-sentence `fix`, and when
they apply `status` (the API's HTTP status), `requestId`,
`retryAfterSeconds`, `errors` (every manifest or bundle problem, or scan
finding: `code`, `path`, `message`, `fix`), `details` (what the refusal is about: `limit`,
`handle`, …) and `reveal` (values you must see although the command failed,
such as a secret minted before its `.env` write broke). The API's own codes are passed on as they are. For example,
`tassyir validate` on a manifest with `handle = "API"` and no reason for its
scope (exit code 4):

```text theme={null}
✗ MANIFEST_INVALID: tassyir.app.toml has 2 problems; the first: `handle` is "API"; a handle is 3 to 40 lowercase letters, digits and single hyphens, starting and ending with a letter or digit.
  Fix: Set `handle` to a handle of that form, e.g. "api". Then fix the others listed and run `tassyir validate` again.
  - MANIFEST_HANDLE_INVALID at handle: `handle` is "API"; a handle is 3 to 40 lowercase letters, digits and single hyphens, starting and ending with a letter or digit.
    Fix: Set `handle` to a handle of that form, e.g. "api".
  - MANIFEST_SCOPE_REASON_MISSING at access.scope_reasons.read_orders: "read_orders" is requested but `access.scope_reasons` does not explain it.
    Fix: Add read_orders = "<one sentence on why the app needs it>" to `access.scope_reasons`.
```

With `--json`, the same (on one line when printed):

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MANIFEST_INVALID",
    "message": "tassyir.app.toml has 2 problems; the first: …",
    "fix": "Set `handle` to a handle of that form, e.g. \"api\". Then fix the others listed and run `tassyir validate` again.",
    "errors": [
      {
        "code": "MANIFEST_HANDLE_INVALID",
        "path": "handle",
        "message": "…",
        "fix": "…"
      },
      {
        "code": "MANIFEST_SCOPE_REASON_MISSING",
        "path": "access.scope_reasons.read_orders",
        "message": "…",
        "fix": "…"
      }
    ]
  }
}
```

| Exit code | Meaning |
| - | - |
| 0 | Done. |
| 1 | Failed: the API refused, or something else went wrong. The `code` says what. |
| 2 | Usage: an unknown command or option, a missing or malformed argument. |
| 3 | Sign in again: not signed in, the token was refused, or the sign-in was denied or expired. |
| 4 | The manifest is missing, not TOML, or invalid, or a hosted app's bundle does not build or pass its checks. Nothing was uploaded. |
| 5 | Try again later: rate limited, or the API is busy or unreachable (`retryAfterSeconds` when known); a hosted version still being scanned, or whose scan ended without a verdict. |

Codes of the CLI's own (the API's pass through as they are):
`NOT_LOGGED_IN`, `LOGIN_DENIED`, `LOGIN_EXPIRED`, `LOGIN_INVALID_GRANT`,
`LOGIN_RATE_LIMITED`, `LOGIN_FAILED`, `TOKEN_ENV_INVALID`, `TOKEN_FROM_ENV`,
`CREDENTIALS_UNAVAILABLE`, `CREDENTIALS_UNREADABLE`, `CREDENTIALS_UNWRITABLE`,
`KEYCHAIN_UNAVAILABLE`, `MANIFEST_NOT_FOUND`, `MANIFEST_UNREADABLE`,
`MANIFEST_TOML_INVALID`, `MANIFEST_INVALID`, `BUNDLE_ENTRY_NOT_FOUND`,
`BUNDLE_BUILD_FAILED`, `BUNDLE_INVALID`, `VERSION_SCAN_FAILED`,
`VERSION_REJECTED`, `VERSION_IN_PROGRESS`, `APP_REQUIRED`, `APP_NOT_FOUND`,
`APP_FIELDS_REQUIRED`, `APP_SECRET_EXISTS`, `ENV_VALUE_EXISTS`,
`ENV_FILE_MISSING`, `ENV_FILE_UNREADABLE`, `ENV_FILE_UNWRITABLE`,
`INSTALLATION_REQUIRED`, `WEBHOOK_ENDPOINT_FAILED`, `WEBHOOK_REPLAY_SKIPPED`,
`COMMAND_NOT_AVAILABLE`, `UNKNOWN_COMMAND`, `INVALID_ARGUMENT`,
`API_ORIGIN_INVALID`, `API_REDIRECTED`, `NETWORK_ERROR`, `TIMEOUT`,
`SERVER_ERROR`, `INVALID_RESPONSE`,
`NODE_VERSION_UNSUPPORTED`, `INTERNAL_ERROR`. A refusal the API sends
without a code (a malformed request, the throttler) reads as `BAD_REQUEST`,
`RATE_LIMITED`, `SERVER_ERROR`, …, by status.

## The manifest

`validate` and `deploy` parse `tassyir.app.toml` and check it with
[`@tassyir/app-manifest`](/packages/app-manifest), the Tassyir API's own validator:
the same normalised manifest, and the same errors in the same order. One
check comes on top: no field of the manifest takes a TOML date or time, so
the CLI refuses one wherever it is (the validator would read a date where a
table goes as an empty table, and the API would see a string there).
`deploy` uploads only a manifest that passed, and the same manifest twice is
answered `unchanged` (exit 0). A hosted app also needs its bundle: see
[Tassyir Hosting](#tassyir-hosting).

## Storefront blocks

Not live yet: blocks open with the marketplace. For each
`[[storefront.blocks]]` entry, `validate` and `deploy` read the template and
the stylesheet (paths from the manifest's folder, never outside it) and hold
them to [`@tassyir/storefront-blocks`](/packages/storefront-blocks)' `validateBlock`,
the check the API runs at upload: the template against its declaration, the
stylesheet, sample renders in Arabic, French and English. Every problem comes
at once as `BLOCKS_INVALID` (exit 4), each with its `code`, its place
(`blocks/product-rating.liquid:3:7`) and a `fix`. A version's block files
weigh 100 KB at most together.

`deploy` then uploads them with the version: an app on your own server sends
them next to the manifest as the version's `assets`
(`{ files: [{ path, content }] }`); a hosted app carries them in its bundle as
text modules, at the manifest's paths. An API that does not take block files
yet answers `BLOCK_ASSETS_NOT_ACCEPTED`.

`tassyir block preview [handle]` renders one block on your machine with the
package's sample data: the store "Dar Amina", a product for target
`product`, each setting at its default. `--lang ar|fr|en` (default `ar`),
`--settings <file.json>` (values as a merchant saves them), `--data <file.json>` (app data by owner: `{ "product": { "rating": … } }`). It prints
the HTML as the store shows it (stdout holds the HTML alone) and warns about
values the render drops; `--out preview.html` writes a page with the
stylesheet, where no script can run.

## The marketplace

Not open yet: these commands drive the API's listing and review routes.

* `tassyir listing pull` writes the draft listing to `./tassyir.listing.json`
  (`--file`; `--force` to overwrite), and lists what it still needs and the
  app's images by id. `tassyir listing push` sends the file back as the whole
  draft: refused with every problem (`LISTING_INVALID`) only for what is never
  right; what is missing is saved and listed. Images are uploaded in the
  developer console.
* `tassyir submit --distribution public|unlisted [--note <text>]` refuses a
  draft that still misses something (`LISTING_INCOMPLETE`), then submits and
  follows the review's automated checklist (`--timeout`, default 180 s; 0
  answers at once). Exit 0 once the review waits for a person, 1 when a hard
  check failed (`SUBMISSION_CHECKS_FAILED`, each check with its fix), 5 when
  it stopped waiting (never submit again then: `tassyir submissions <id> --follow`). The developer terms are accepted in the console, never by the
  CLI.
* `tassyir submit --checks-only` runs the same checklist as a dry run,
  without submitting (5 runs per app per hour: it sends test webhooks to your
  endpoints).
* `tassyir submissions [id] [--follow]` lists the reviews, or shows one: its
  state, why a person reviews it, the turnaround, each check, the decision.

The guide: [Publishing to the marketplace](https://developers.tassyir.io/guides/publishing).

## Tassyir Hosting

For `hosting.mode = "tassyir"`, `deploy` does four things, and stops at the
first that fails. `deploy --dry-run` does the first two only (below).

`tassyir app init --template hosted` starts such a project (a Worker on Hono
and a React page, `create-tassyir-app`'s `hosted` template), and prints its
own next steps: `npm run check`, `tassyir app create`, `npm run deploy` (the
page's build, then `deploy`) and `tassyir store create`. A hosted app needs
no client secret: `tassyir app create` says so by leaving
`tassyir secrets create` out of its next steps.

**1. Build.** esbuild (0.28.2, a dependency of the CLI) bundles the Worker's
entry into one ES module, `worker.js`: `--entry <file>`, or the first of
`src/worker.ts`, `src/worker.js`, `src/index.ts`, `src/index.js` in the
manifest's folder. Target ES2022, the `workerd` / `worker` / `browser` export
conditions, `.html` and `.css` imported as text (`import page from
'./page.html'` is a string). `cloudflare:*` and `node:*` stay imports, so the
checks can name them. The source map stays on your machine: the checks use
it to point at your source, and a bundle never carries one. A build error
is `BUNDLE_BUILD_FAILED` (exit 4) with each of esbuild's errors in `errors`
(a package that is not installed, a Node.js built-in, a binary file).

**2. Check, before anything is sent.** The same rules the API applies, so a
bundle the CLI passes is one the API takes:

* the API's upload rules (`BUNDLE_*` codes, exactly the API's): 1 to 100
  files, at most 3 MB of UTF-8 together; text only (ES modules `.js` /
  `.mjs`, text `.html` `.css` `.txt` `.json` `.svg` `.liquid`), no
  WebAssembly, source map or binary; paths of letters, digits, `.`, `_`, `-`
  that never start with `.`, at most 200 characters and in at most 9
  folders (`a/b/c.js` is in 2); `main` one of the ES modules; a lockfile of
  at most 1 MB;
* the code checks of the scan that do not need Tassyir's data: `eval` or
  `new Function` over code built at run time, a string timer,
  `.constructor.constructor()`, `import()` of a name built at run time, an
  import of a URL, of `cloudflare:sockets` or of anything outside the
  bundle (`BUNDLE_DYNAMIC_IMPORT`, `BUNDLE_EVAL`, …), a `node:` import
  (`BUNDLE_NODE_IMPORT`: a hosted Worker has no Node.js compatibility), a
  `main` that surely exports no `fetch` handler (`BUNDLE_NO_FETCH_HANDLER`;
  a default built at run time, inherited or re-exported passes), and every
  `fetch` / `new Request` / `new WebSocket` / `new EventSource` to a literal
  host: a Tassyir domain (`BUNDLE_TASSYIR_HOST`: call Tassyir through
  `ctx.props.TASSYIR`), a host outside `hosting.allowed_hosts`
  (`BUNDLE_HOST_NOT_ALLOWED`; `*.x.com` is the subdomains of `x.com`, never
  `x.com`), or http.

Every problem at once is `BUNDLE_INVALID` (exit 4), each in `errors` with its
place in your source (`src/worker.ts:12`). What the scan would only warn
about (`eval("…")` of a literal, a host built at run time, WebAssembly) is
printed and does not stop the deploy. The scan's other checks (invisible
Unicode, Admin API calls against the requested scopes, Semgrep, Gitleaks,
OSV on the lockfile, the AI review) run on Tassyir's side only.

**`--dry-run` stops here.** It builds and checks exactly as above, with no
sign-in and nothing sent: exit 0 when `deploy` would upload the bundle, 4
when it would refuse it (`BUNDLE_INVALID`, `BUNDLE_BUILD_FAILED`, or the
manifest's own `MANIFEST_INVALID`). `--app` and `--timeout` are not used
(a warning says so). The hosted template's `npm run deploy:check` is the
page's build, then `tassyir deploy --dry-run`. For an app on your own server,
`--dry-run` checks the manifest only.

```bash theme={null}
tassyir deploy --dry-run --json
```

```json theme={null}
{
  "ok": true,
  "dryRun": true,
  "uploaded": false,
  "app": { "handle": "review-requests" },
  "hosting": "tassyir",
  "entry": "src/worker.ts",
  "main": "worker.js",
  "bytes": 398412,
  "lockfile": "package-lock.json",
  "warnings": [],
  "next": "tassyir deploy"
}
```

**3. Upload** `{ manifest, bundle: { main, files, lockfile } }` to
`POST developer/apps/{appId}/versions`. The lockfile is the project's
`package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock` or
`bun.lock` (the first found, in that order), scanned for known
vulnerabilities and malicious packages, never deployed. Without one the scan
warns that the dependencies were not checked.

**4. Follow the scan.** Every 10 seconds the CLI reads the version
(`GET developer/apps/{appId}/versions/{n}`) until it settles, or `--timeout`
seconds pass (default 1800, the time the API gives a scan; `0` answers at
once). A busy or unreachable API is asked again. Ctrl-C stops waiting, never
the scan. Then:

| The version | `deploy` |
| - | - |
| Released (`approved`): scanned, on Cloudflare | exit 0, `"released": true`, the findings that only warned |
| Held for a person (`in_review`) | exit 0, `"released": false`, `"state": "in_review"`: the checks passed, the AI review asked for a look |
| Failed its scan (`scan_failed`, on findings) | exit 1, `VERSION_SCAN_FAILED`, every failing finding and review concern in `errors` |
| Its scan ended without a verdict | exit 5, the API's code (`SCAN_TIMED_OUT`, `SCAN_INCOMPLETE`, `SCAN_DISPATCH_FAILED`, `SCAN_RESULT_INVALID`): upload the same bundle again |
| Scanned, but the upload to Cloudflare failed | exit 1, the API's code (`CLOUDFLARE_REJECTED`, …) and, when it sent one, Cloudflare's own code and message (`refusal`) |
| Rejected by a person at Tassyir | exit 1, `VERSION_REJECTED` with the reason |
| Still scanning at `--timeout`, or after Ctrl-C | exit 5, `VERSION_IN_PROGRESS`: `tassyir app version <n> --follow` picks it up |

Every answer carries the whole version as the API sent it (`version`, or
`error.details.version`): the scan's `status` and `reasons`, each check with
its findings (`rule`, `severity`, `file`, `line`, `message`), the AI review,
and both uploads. `tassyir app version [n]` shows it again; with `--follow`
it waits and exits as `deploy` does.

```bash theme={null}
tassyir deploy --json
```

```json theme={null}
{ "ok": true, "step": "uploaded", "app": { "id": "741…", "handle": "review-requests" }, "unchanged": false, "version": { "version": 3, "reviewState": "scanning", "scan": "pending" }, "next": "tassyir app version 3 --follow --app review-requests" }
{ "ok": true, "released": true, "state": "released", "unchanged": false, "app": { "…": "…" }, "version": { "version": 3, "reviewState": "approved", "current": true, "hosting": { "scan": { "status": "passed", "…": "…" }, "checks": ["…"], "review": null, "…": "…" } }, "warnings": [] }
```

The same manifest and bundle as the latest version are not a new version
(`APP_VERSION_UNCHANGED`): `deploy` answers with that version's state, and
follows it if its scan is still running. After a scan that ended without a
verdict, the same bundle is scanned again as a new version. The API's
refusals of a hosted upload, with the CLI's fix:

| Code | Why, and what to do |
| - | - |
| `APP_HOSTING_NOT_AVAILABLE` | Tassyir Hosting is off on this API (production, for now): run the app on your own server, or use `--api-origin`. |
| `APP_HOSTING_NOT_CONFIGURED` | On, but not ready to take uploads; nothing was stored (exit 5): try again later. |
| `APP_VERSION_CONFLICT` | Another upload of the app took the version number first: run `tassyir deploy` again. |
| `APP_HOSTING_BUSY` | Tassyir scanned all it can for today (exit 5, `retryAfterSeconds`). |
| `DEVELOPER_RATE_LIMITED` | 10 hosted versions per developer per 24 hours (each is a scan), 30 versions an hour. |
| `APP_BUNDLE_INVALID` | The API refused what the CLI's check passed (exit 4, `errors`): update the CLI. |
| `PAYLOAD_TOO_LARGE` | An upload is at most 128 KB where Tassyir Hosting is off, 8 MB + 128 KB where it is on: the API's `fix` and `limitBytes` say which. |

## From code

The package's entry runs a command line in-process, with your own I/O (the
specs do this against a fake API):

```ts theme={null}
import { runCli } from 'tassyir';

const exitCode = await runCli(['validate', '--json'], io);
```

`io` is a `CliIo`: stdout, stderr, the environment, the working folder,
`fetch`, a clock, how to run a program and, optionally, Ctrl-C
(`onInterrupt`). The hosted bundle's checks are exported too:
`validateHostedBundle` (the API's upload rules), `checkBundleCode` (the
scan's code checks) and `buildHostedBundle`; and the block files' check,
`checkBlocks` (what `validate` runs on `[[storefront.blocks]]`). `DeveloperApi` is the typed
developer-API client the commands use. Its routes, bodies and answers are
typed from the developer API's OpenAPI document, vendored in `openapi/` at a
recorded backend commit (`SOURCE.json`); the package exports the types
(`DeveloperApp`, `Installation`, `Delivery`, `WebhookTopic`, …, and the raw
`DeveloperApiPaths`, `DeveloperApiOperations`, `DeveloperApiComponents`). In
this repo, with a clone of `tassyir/backend` in `TASSYIR_BACKEND_DIR`,
`npm run openapi:check -w tassyir` compares the copy with the backend's and
`npm run openapi:update -w tassyir` vendors the new file and regenerates the
types.

## License

MIT


# create-tassyir-app
Source: https://developers.tassyir.io/packages/create-tassyir-app

Start a Tassyir app: npm create tassyir-app@latest. A Node server with an embedded page, webhooks and the Admin API, ready for AI coding agents (AGENTS.md, CLAUDE.md, a Claude Code skill).

Starts a [Tassyir](https://tassyir.io) app, on your own server (the
`external` template, the default) or on Tassyir Hosting (`hosted`: Tassyir
runs it, no server). Either project uses the app contract end to end: the
manifest, an embedded page in the dashboard, the Admin API and webhooks. It
is ready for AI coding agents: an `AGENTS.md`, a `CLAUDE.md` and a Claude
Code skill (`tassyir-app`) that explains the contract, both hosting modes.

## Use

Node 22.18 or later:

```bash theme={null}
npm create tassyir-app@latest my-app
```

It writes `my-app/` and prints the next steps. The project's README walks
the rest: for `external`, create the app in the developer console, upload the
manifest, create a dev store, run behind an https tunnel, and install; for
`hosted`, `tassyir app create`, `npm run deploy`, `tassyir store create`, and
install.

```bash theme={null}
npm create tassyir-app@latest my-app -- --template hosted
```

With options (after `--`, which npm needs to pass them on):

```bash theme={null}
npm create tassyir-app@latest my-app -- --handle review-requests --name "Review Requests" --json
```

| Option | Meaning |
| - | - |
| `--handle <handle>` | The app's handle: permanent and unique on Tassyir. Default: the folder's name. |
| `--name <name>` | The display name. Default: the handle in words. |
| `--url <url>` | `external` only: the server's public https address (`hosting.url`). Default: a placeholder to replace. |
| `--template <name>` | `external` (default, your own server) or `hosted` (Tassyir Hosting). |
| `--install` | Runs `npm install` in the new folder. |
| `--json` | Prints one JSON document, the result or the error, and never asks anything. |
| `-y`, `--yes` | Never asks: uses the defaults. |

The handle, name and URL are checked with the manifest's own rules
(`@tassyir/app-manifest`, the Tassyir API's validator) before anything is
written, and nothing is ever written into a folder that is not empty.

## The projects

`external`, your own server:

```
tassyir.app.toml        the manifest; npm run validate checks it with the API's validator
src/server.ts           Node 22 entry (Hono on @hono/node-server)
src/app.ts              routes: /health, /webhooks, /api/* (ID token → Admin API), the page
src/webhooks.ts         verifies deliveries on the raw body, dedupes on webhook-id
src/store.ts            the token store behind @tassyir/app's TokenStore: one file, tokens encrypted
src/page/               the embedded page on @tassyir/app-bridge and @tassyir/ui (ar/en, rtl, dark)
test/                   specs against a fake Tassyir API; no network, no account
AGENTS.md, CLAUDE.md, .claude/skills/tassyir-app/SKILL.md
```

Why Hono: it is built on the Web-standard `Request` and `Response`, like
`@tassyir/app` (fetch and WebCrypto only), so the same routes run on Node
today and on Cloudflare Workers, which Tassyir Hosting is built on. Node runs
the TypeScript as it is (type stripping, Node 22.18 and later), so the
server has no build step; esbuild bundles the page.

`hosted`, on Tassyir Hosting (a Cloudflare Worker that Tassyir runs for every
installation):

```
tassyir.app.toml        hosting.mode = "tassyir", allowed_hosts, the page, webhooks
src/worker.ts           what Tassyir runs: the routes with the built page inside, one ES module
src/app.ts              routes (Hono): ctx.props, /webhooks, /api/* (ctx.props.TASSYIR → Admin API), the page
src/storage.ts          ctx.props.STORAGE: the installation's own SQLite database
src/webhooks.ts         verifyHostedWebhook: the signature (keys through TASSYIR), this installation
src/page/               a React page on @tassyir/app-bridge/react and @tassyir/ui (ar/en, rtl, dark)
test/worker/            specs in workerd (Cloudflare's Vitest integration) with stand-in ctx.props
AGENTS.md, CLAUDE.md, .claude/skills/tassyir-app/SKILL.md
```

It holds no secret and no `.env`: a hosted app reads its installation, who
is looking, its storage and the Admin API from `ctx.props`, per request.
`npm run check` validates, typechecks, runs the specs and `deploy:check`
(`tassyir deploy --dry-run`: the bundle built and checked, nothing uploaded);
`npm run deploy` is `tassyir deploy`.

The generated `package.json` names the versions of this repo's packages
released with this version of `create-tassyir-app` (`@tassyir/*`, and
`tassyir` for `hosted`), and pins every other dependency to an exact
version.

## Errors

A refusal has a stable `code`, the input at fault (`path`: `--handle`,
`--url`, `directory`, …), a `message` and a one-sentence `fix`; `problems`
lists every problem found, this one first. With `--json`
(`npm create tassyir-app@latest my-app -- --handle tassyir --json`):

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MANIFEST_HANDLE_RESERVED",
    "path": "--handle",
    "message": "`handle` is \"tassyir\", which Tassyir reserves.",
    "fix": "Choose another handle, e.g. \"tassyir-app\" or one naming what the app does.",
    "problems": [
      {
        "code": "MANIFEST_HANDLE_RESERVED",
        "path": "--handle",
        "message": "`handle` is \"tassyir\", which Tassyir reserves.",
        "fix": "Choose another handle, e.g. \"tassyir-app\" or one naming what the app does."
      }
    ]
  }
}
```

Codes: `TEMPLATE_UNKNOWN`, `TEMPLATE_NOT_AVAILABLE`,
`OPTION_NOT_FOR_TEMPLATE` (`--url` with `hosted`), `TARGET_NOT_EMPTY`,
`TARGET_NOT_A_DIRECTORY`, `INVALID_ARGUMENT`, `NODE_VERSION_UNSUPPORTED`,
`WRITE_FAILED`, `INSTALL_FAILED`, and the manifest's own codes for the
handle, name and URL (`MANIFEST_HANDLE_INVALID`, `MANIFEST_URL_INVALID`, …).

## From code

```ts theme={null}
import { createProject, isCreateError } from 'create-tassyir-app';

try {
  const project = await createProject({
    directory: 'review-requests',
    name: 'Review Requests',
  });
  console.log(project.files.length, project.app.handle);
} catch (error) {
  if (isCreateError(error)) console.error(error.code, error.fix);
  else throw error;
}
```

## Contributing

In a clone of [tassyir/apps-sdk](https://github.com/tassyir/apps-sdk), CI
generates a project of each template with the packed CLI and checks it whole
(`npm run check:template`). The pages are also checked in a real browser,
locally:

```bash theme={null}
npm run build && npm run check:template -- --keep
```

```bash theme={null}
npm run browser-check -w create-tassyir-app -- <the folder it kept> --out shots
```

```bash theme={null}
npm run browser-check -w create-tassyir-app -- <the folder it kept> --template hosted --out shots
```

It starts the project's own server (its real Content-Security-Policy; for
`hosted`, the Worker's routes run by Node with stand-in `ctx.props`),
frames the page in a fake dashboard at `https://app.tassyir.io` that answers
App Bridge, answers the page's `/api` calls with sample orders, and drives a
headless Chrome over the DevTools protocol. It checks the page in Arabic and
English, light and dark, at 390 and 1440 px (`lang`, `dir` and theme, the
frame's width, no error and no CSP violation, the title bar), then the save
bar, a field error, a save (with a fresh ID token; the hosted page sends
none), Open, a live change of
language and theme, and the empty state, with a screenshot of each in
`--out`. It needs `openssl`; `CHROME_PATH` names a Chrome other than macOS
Google Chrome.

## License

MIT


# @tassyir/dev-mcp
Source: https://developers.tassyir.io/packages/dev-mcp

An MCP server for the AI agent that builds your Tassyir app: the guides, the Admin API and webhook schemas, manifest validation, the starter, and test webhooks and dev stores through your tassyir login.

An [MCP](https://modelcontextprotocol.io) server for the AI coding agent that
builds your [Tassyir](https://tassyir.io) app (Claude Code, Cursor, Codex or
any MCP client). In one place, your agent can:

* search and read Tassyir's developer guides;
* look up any Admin API operation (scope, parameters, body, every error code)
  and any webhook topic's body, and any operation of the developer API the
  `tassyir` CLI calls;
* validate `tassyir.app.toml` with the Tassyir API's own validator;
* start a new app from the official starter;
* send a test webhook to your app and create seeded dev stores, with your
  `tassyir login`.

It runs on your machine over stdio. The guides and the API references ship
inside the package (the Admin API at version `2026-10`, and the developer
API), so the reference tools work offline and answer from the version you
installed.

## Install

Node 22.18 or later.

### Claude Code plugin

In Claude Code, add Tassyir's plugin marketplace (this repository) and
install its `tassyir` plugin:

```text theme={null}
/plugin marketplace add tassyir/apps-sdk
/plugin install tassyir@tassyir
```

The plugin runs this server (`npx -y @tassyir/dev-mcp@<version>`, the
release the plugin names) and adds the `tassyir-app` skill: the app contract
(manifest, scopes, tokens, webhooks, Admin API, App Bridge, dev stores) that
`create-tassyir-app` also writes into every new project's
`.claude/skills`, the same file. From a terminal, the same is
`claude plugin marketplace add tassyir/apps-sdk` then
`claude plugin install tassyir@tassyir`. For a newer release later, run
`claude plugin marketplace update tassyir`, then
`claude plugin update tassyir@tassyir`.

### The server alone

In Claude Code:

```bash theme={null}
claude mcp add tassyir -- npx -y @tassyir/dev-mcp
```

`--scope project` writes it to the project's `.mcp.json` instead, for everyone
who works on the app. Any other MCP client takes the same command:

```json theme={null}
{
  "mcpServers": {
    "tassyir": { "command": "npx", "args": ["-y", "@tassyir/dev-mcp"] }
  }
}
```

The client starts the server in your project's folder: relative paths, and
the `tassyir.app.toml` the tools read by default, are resolved from there.

The tools that act on your Tassyir account (`trigger_test_webhook`,
`seed_dev_store`, `list_dev_stores`, `run_review_checks`) use the sign-in of the
[`tassyir` CLI](/packages/cli). Sign in once, in a terminal:

```bash theme={null}
npx tassyir login
```

## Example

Ask your agent: *"Start a Tassyir app called Review Requests that asks for a
review when an order is delivered, and send it a test `orders/delivered`
webhook."* It can then:

1. `search_docs { "query": "orders/delivered" }` → the topic, the webhooks
   guide, the orders guide, each with the tool call that reads it;
2. `scaffold { "directory": "review-requests" }` → the starter, its files and
   the next steps;
3. `get_event_schema { "topic": "orders/delivered" }` → the envelope, the
   order resource, the headers to verify;
4. edit the manifest, then `validate_manifest {}` → `valid`, or every problem
   with its `code`, field `path` and `fix`;
5. after `tassyir deploy` and the install on a dev store,
   `trigger_test_webhook { "topic": "orders/delivered" }` → what the app's
   endpoint answered, with a fix when it was not 2xx.

A refusal is an MCP error result whose structured content is
`{ "error": { "code", "message", "fix", … } }`:

```json theme={null}
{
  "error": {
    "code": "NOT_LOGGED_IN",
    "message": "Not signed in to https://api.tassyir.io on this machine",
    "fix": "Ask your user to run `npx tassyir login` in a terminal and approve the code in the Tassyir dashboard, then call this tool again (in CI: set TASSYIR_TOKEN). Never ask them for the token itself."
  }
}
```

Arguments that do not match a tool's input schema never reach the tool: the
MCP SDK refuses them first, with its own validation message naming the field.

## Tools

| Tool | What it does |
| - | - |
| `search_docs` | Searches the guides, the Admin API's operations and the webhook topics; each result names the tool call that reads it. |
| `fetch_doc` | Reads a guide as Markdown, a page (about 3,500 characters) or a section at a time, with its address on developers.tassyir.io; without a slug, lists the guides. |
| `get_api_operation` | One Admin API operation (by `operationId` or `METHOD /path`), one component schema, or the list of operations; `"api": "developer"` for the developer API the CLI calls. |
| `get_event_schema` | One webhook topic: envelope, resource, headers, the scope to subscribe, the answer to give; without a topic, the list. |
| `validate_manifest` | Validates `tassyir.app.toml` (its text, a path, or `./tassyir.app.toml`) with `@tassyir/app-manifest`, as the API will. |
| `scaffold` | Writes a new app from `create-tassyir-app` into a new or empty folder; never overwrites, installs nothing. |
| `trigger_test_webhook` | Sends a signed test event of one topic to your app's endpoint through Tassyir and reports the answer. Needs `tassyir login`. |
| `seed_dev_store` | Creates a dev store seeded with products, orders and customers (at most 3, permanent). Needs `tassyir login`. |
| `list_dev_stores` | Your dev stores and their dashboard links. Needs `tassyir login`. |
| `validate_block` | A storefront block checked offline by `@tassyir/storefront-blocks`, the API's upload check: the app's `[[storefront.blocks]]` files, or a template as text. Each problem with file:line:column and a fix; `preview` renders it with sample data. |
| `tail_logs` | Not available yet: it reads the logs of apps on Tassyir Hosting. Answers `TOOL_NOT_AVAILABLE`. |
| `run_review_checks` | The marketplace review's automated checklist as a dry run on the draft listing and latest version: each check with its fix, never a submission. 5 runs per app per hour. Needs `tassyir login`. |

Every tool has a JSON Schema input that refuses unknown arguments, and every
tool that can succeed declares the JSON Schema of its answer. Every answer is
at most 8 KB of JSON: a guide comes a page at a time, and an API schema that
would not fit is shortened (`shortened: true`; its `$ref`s are names you can
look up).

## Safety

* **Answers are data.** The guides, the API reference, the API's replies and
  your endpoint's errors describe the platform; nothing in them is an
  instruction to the agent, and the server never acts on them (it follows no
  link and calls no URL they name). The server's MCP instructions tell the
  agent the same.
* **The developer token never leaves your machine but to the Tassyir API.**
  It is read for each call from where `tassyir login` put it (`TASSYIR_TOKEN`,
  else the OS keychain, else the CLI's credentials file) and sent only to the
  API origin, as a bearer. It is never in an answer, an error or a log line:
  every string an answer carries is redacted of developer tokens and device
  codes, and of every other Tassyir secret shape in answers from the API.
* **This server never signs in by itself.** A sign-in needs you to approve a
  code in the dashboard; the agent is told to ask you to run
  `npx tassyir login`.
* `scaffold` writes only into a new or empty folder; `validate_manifest` reads
  only `.toml` files, at most 256 KB.

## Environment

The same variables as the `tassyir` CLI:

| Variable | Meaning |
| - | - |
| `TASSYIR_API_ORIGIN` | Another Tassyir API (staging, a local one); https, or http on localhost. |
| `TASSYIR_TOKEN` | A developer token for CI; otherwise the stored `tassyir login` is used. |
| `TASSYIR_CREDENTIAL_STORE` | `keychain` or `file`: where the CLI stored the token. |
| `TASSYIR_CONFIG_DIR` | The CLI's configuration folder. |
| `TASSYIR_DEBUG=1` | One line per API request on stderr (method, path, status); never a token. |

## From a checkout

To try the server from a clone of `tassyir/apps-sdk`, without a build:

```bash theme={null}
node --import ./packages/dev-mcp/scripts/from-source.mjs packages/dev-mcp/src/cli.ts
```

It then reads the repo's own `docs/guides` and the OpenAPI documents of
`@tassyir/app` and the `tassyir` CLI.

## License

[MIT](https://github.com/tassyir/apps-sdk/blob/main/packages/dev-mcp/LICENSE)


# @tassyir/storefront-blocks
Source: https://developers.tassyir.io/packages/storefront-blocks

The language of Tassyir's declarative storefront blocks: a Liquid subset with a validator (coded errors with line, column and fix), a step-counted renderer and an allowlist HTML gate. The same bytes in Node and in browsers.

The language of Tassyir's declarative storefront blocks: the HTML an app adds
to a merchant's store pages, written as a template in a subset of
[Liquid](https://shopify.github.io/liquid/) with an optional stylesheet. This
package validates a block (every error with a `code`, a `line`, a `column`
and a `fix`) and renders it. The Tassyir API checks uploads with it, the
store builder previews with it, the storefront renders with it, and the
`tassyir` CLI uses it for `tassyir block preview`: one code, the same answer
everywhere.

**Not live yet.** Storefront blocks open with the Tassyir app marketplace.
Until then the API refuses `[[storefront.blocks]]` in a manifest. The
language is published now so that you can write and test blocks.

It has no dependency and reads no file, clock, network or randomness. It
never uses `Intl`. The same template and data give the same bytes in Node and
in every browser. ESM and CommonJS, named exports only.

## Install

```bash theme={null}
npm install @tassyir/storefront-blocks
```

## Example

A block that shows a product's rating, read from the app's data:

```ts theme={null}
import {
  renderBlock,
  sampleBlockContext,
  validateBlock,
} from '@tassyir/storefront-blocks';
import type { BlockDeclaration } from '@tassyir/storefront-blocks';

const declaration: BlockDeclaration = {
  target: 'product',
  settings: [
    {
      key: 'title',
      type: 'text',
      default: { ar: 'آراء الزبائن', en: 'Reviews' },
    },
    { key: 'accent_color', type: 'color', default: '#0b6e4f' },
  ],
  data: ['product.rating'],
};

const template = `<section class="rating">
  <h3>{{ block.settings.title | t }}</h3>
  {%- assign rating = app.data.product.rating -%}
  {%- if rating %}
  <p>{{ rating.average | stars }} <small>({{ rating.count }})</small></p>
  {%- else %}
  <p>{{ product.name }}</p>
  {%- endif %}
</section>`;

const stylesheet = `.rating { color: var(--block-accent-color); border-radius: var(--st-radius); }`;

// The upload check: the template, the stylesheet, and a render with sample data.
const check = validateBlock({ template, stylesheet, declaration });
if (!check.ok) {
  for (const error of check.errors) {
    console.error(
      `${error.code} ${error.source}:${String(error.line)}:${String(error.column)} ${error.message} ${error.fix}`,
    );
  }
  process.exit(1);
}

// A preview with sample data and your own app data.
const result = renderBlock(
  template,
  sampleBlockContext(declaration, {
    language: 'en',
    appData: { product: { rating: { average: 4.4, count: 128 } } },
  }),
  declaration,
);
if (result.ok) console.log(result.html);
```

Rendered (byte for byte, the README's spec checks it):

```text theme={null}
<section class="rating">
  <h3>Reviews</h3>
  <p><span class="tsy-stars" role="img" aria-label="Rated 4.4 out of 5">★★★★☆</span> <small>(128)</small></p>
</section>
```

The full language (objects, tags, filters, HTML and CSS rules) is in the
[storefront blocks guide](https://developers.tassyir.io/guides/storefront-blocks).

## What you get back

`validateBlock`, `compileBlockTemplate` and `renderBlock` never throw. They
return `{ ok: true, … }` or `{ ok: false, errors }`. Each error has this shape:

```ts theme={null}
interface BlockError {
  code: BlockErrorCode; // stable: switch on it
  source: 'template' | 'stylesheet' | 'render';
  line: number; // 1-based; 0 for a render limit
  column: number; // 1-based, in UTF-16 code units, as editors count
  message: string;
  fix: string; // one sentence to act on
}
```

Errors are sorted by position, at most 50 per file (the last one says how
many more there were). The same input always gives the same errors in the same
order.

| Code | When |
| - | - |
| `BLOCK_TEMPLATE_NOT_TEXT` | The template (or stylesheet) is not a string, or holds a NUL character. |
| `BLOCK_TEMPLATE_EMPTY` | The template is empty or only spaces. |
| `BLOCK_TEMPLATE_TOO_LARGE` | Over 16 KB. |
| `BLOCK_STYLESHEET_TOO_LARGE` | Over 8 KB. |
| `BLOCK_CHARACTER_NOT_ALLOWED` | A bidi override or isolate, an invisible or control character, `<` in a stylesheet. |
| `BLOCK_LIQUID_UNTERMINATED` | `{{` or `{%` never closed. |
| `BLOCK_LIQUID_SYNTAX` | An expression the language cannot read. |
| `BLOCK_TAG_UNKNOWN` | A tag Liquid does not have. |
| `BLOCK_TAG_NOT_SUPPORTED` | A Liquid tag blocks do not have (`include`, `render`, `raw`, `form`, `schema`, …). |
| `BLOCK_TAG_UNCLOSED` | `if`, `for`, `case`, `capture` or `comment` without its end tag. |
| `BLOCK_TAG_UNEXPECTED` | An end, `else`, `elsif`, `when`, `break` or `continue` outside its block. |
| `BLOCK_NESTING_TOO_DEEP` | More than 10 Liquid blocks inside one another. |
| `BLOCK_LOOP_NESTING_TOO_DEEP` | More than 3 `for` loops inside one another. |
| `BLOCK_LOOP_LIMIT_TOO_HIGH` | A literal `limit:` or range over 50. |
| `BLOCK_FILTER_UNKNOWN` | A filter that does not exist. |
| `BLOCK_FILTER_NOT_SUPPORTED` | A Liquid filter blocks do not have (`raw`, `date`, `json`, `img_url`, …). |
| `BLOCK_FILTER_ARGUMENTS` | The wrong number of arguments, or a named argument. |
| `BLOCK_FILTER_CHAIN_TOO_LONG` | More than 10 filters in one expression. |
| `BLOCK_VARIABLE_UNKNOWN` | A name that is neither a block object nor a variable the template assigns. |
| `BLOCK_OBJECT_NOT_AVAILABLE` | `product` (or product app data) in a block whose target is not `product`. |
| `BLOCK_PROPERTY_UNKNOWN` | A property the object does not have (`store.phone`). |
| `BLOCK_SETTING_UNDECLARED` | A setting (`block.settings.x`, `var(--block-x)`) the block does not declare. |
| `BLOCK_DATA_KEY_UNDECLARED` | App data the block does not list in its `data`. |
| `BLOCK_DATA_OWNER_UNKNOWN` | App data of an owner blocks cannot read (`order`, `customer`). |
| `BLOCK_ASSIGN_RESERVED` | Assigning `block`, `product`, `store`, `app` or `forloop`. |
| `BLOCK_TOO_MANY_VARIABLES` | More than 64 variables. |
| `BLOCK_HTML_TAG_NOT_ALLOWED` | An element blocks cannot use (`script`, `style`, `form`, `iframe`, `h1`, …). |
| `BLOCK_HTML_ATTRIBUTE_NOT_ALLOWED` | An attribute blocks cannot use (`id`, `data-*`, …). |
| `BLOCK_HTML_STYLE_ATTRIBUTE` | A `style` attribute. |
| `BLOCK_HTML_EVENT_HANDLER` | An `on…` attribute. |
| `BLOCK_HTML_URL_NOT_ALLOWED` | A link that is not `https://`, a store path or a `#fragment`. |
| `BLOCK_HTML_IMAGE_SOURCE` | An `<img>` whose `src` is not one `{{ … \| image_url: <width> }}`. |
| `BLOCK_HTML_ATTRIBUTE_VALUE` | A value the attribute does not accept, or `stars` inside an attribute. |
| `BLOCK_HTML_DYNAMIC_TAG` | An element name made by Liquid (`<{{ x }}>`). |
| `BLOCK_HTML_DYNAMIC_ATTRIBUTE` | An attribute name made by Liquid. |
| `BLOCK_HTML_UNQUOTED_ATTRIBUTE` | Liquid in an attribute value without quotes. |
| `BLOCK_HTML_UNTERMINATED_TAG` | A tag never closed with `>`. |
| `BLOCK_HTML_TOO_DEEP` | More than 32 elements inside one another. |
| `BLOCK_HTML_ENTITY_UNKNOWN` | A named character reference the language does not know. |
| `BLOCK_CSS_SYNTAX` | An unclosed string, comment, bracket or block, a nested rule. |
| `BLOCK_CSS_AT_RULE_NOT_ALLOWED` | An at-rule other than `@media`, `@supports` and `@keyframes <name>`. |
| `BLOCK_CSS_URL_NOT_ALLOWED` | A `url()` outside `https://cdn.tassyir.io/`. |
| `BLOCK_CSS_FUNCTION_NOT_ALLOWED` | A CSS function blocks cannot use (`expression()`, `image-set()`, …). |
| `BLOCK_CSS_DECLARATION_NOT_ALLOWED` | `position` not one written `static`/`relative`/`absolute`/`sticky`; `behavior`, `-moz-binding`. |
| `BLOCK_CSS_ESCAPE_NOT_ALLOWED` | A backslash escape outside a quoted string. |
| `BLOCK_CSS_THEME_VARIABLE_UNKNOWN` | A `--st-*` variable that is not published. |
| `BLOCK_RENDER_CONTEXT_INVALID` | The render context has no store. |
| `BLOCK_RENDER_STEP_LIMIT` | The render used more than 20,000 steps. |
| `BLOCK_RENDER_OUTPUT_LIMIT` | The rendered HTML is over 32 KB. |
| `BLOCK_RENDER_STRING_LIMIT` | A string the template builds is over 32,768 characters. |
| `BLOCK_RENDER_ARRAY_LIMIT` | A list the template builds has more than 500 items. |
| `BLOCK_RENDER_DATA_TOO_LARGE` | The data is over 32 KB, nested deeper than 16, or holds a list of more than 500 items. |
| `BLOCK_RENDER_FAILED` | The renderer stopped on an error it does not name (report it). |

## Limits

All in `BLOCK_LIMITS`, the same everywhere:

| Limit | Value |
| - | - |
| Template | 16 KB |
| Stylesheet | 8 KB |
| Blocks per app version | 20 |
| Block files per version | 100 KB |
| Rendered HTML | 32 KB |
| App data one render reads | 32 KB |
| Render work | 20,000 steps |
| Iterations of one `for` loop | 50 |
| `for` loops inside one another | 3 |
| Liquid blocks inside one another | 10 |
| HTML elements inside one another | 32 |
| Filters in one expression | 10 |
| Variables | 64 |
| Items in a list a template builds | 500 |
| Characters in a string a template builds | 32,768 |

Render time is counted in **steps**, never measured with a clock: every text
run, output, tag, loop iteration and condition costs a step, and every filter
and comparison one more per 256 characters or items it touches. The same
template and data always finish, or always stop at the same step. The heaviest
render the budget allows takes a few milliseconds.

## How it stays safe

A block runs on the page that holds the store's order form, so the language
is built to make anything else impossible:

* **Every output is escaped.** There is no `raw` filter and no way to turn
  escaping off. Only Tassyir's own `stars` filter makes markup, from fixed
  parts.
* **No prototype, method or getter is reachable.** The data a render is given
  is copied into maps and frozen arrays; a template reads own keys and indexes
  only.
* **The HTML is rebuilt, not filtered.** Every render's output is parsed and
  written out again from an allowlist (`BLOCK_HTML_ALLOWLIST`): allowed
  elements and attributes only, every value checked and quoted, every text
  escaped, comments and raw-text elements removed, SVG shapes only inside
  `<svg>`. The browser parses that canonical HTML, never the template's.
  Sanitising the output again leaves it unchanged.
* **Only declared data reaches the template.** A compiled template keeps its
  declaration's app data keys and setting keys, and a render passes the
  template only those, through every alias (`{% assign d = app.data.store %}`).
* **Execution is bounded by counting**, never by a clock, so the bound holds
  on every machine and cannot be raced.
* **The box is the host's.** This package decides what the HTML and the
  stylesheet may say; it cannot keep a block's pixels inside its section. The
  page that renders a block must contain it: `contain: paint` (and
  `isolation: isolate`) on the block's section. The stylesheet check refuses
  `position: fixed` in every spelling, but `position: absolute`, transforms
  and the page's own utility classes are ordinary CSS that only containment
  keeps in the box.
* **Nothing differs between machines**: no `Intl`, no clock, no randomness, no
  locale method, no Unicode property table.

Why not a Liquid engine with features switched off: an engine brings its
tags (file includes among them), its filters (the clock, locale formatting)
and its options to keep switched off release after release. Its time limit is
a wall clock checked between renders, not inside a loop. This package has
only what blocks need, so there is nothing to switch off.

The proof is in the specs: a seeded corpus of more than 1,600 templates and
data planted with known sanitiser bypasses (tag and attribute smuggling,
raw-text and SVG/MathML parser switches, `javascript:` and `data:` URLs in
their encodings, character-reference tricks, bidi and zero-width characters,
CSS `url()` and `expression()`, deep nesting, huge loops), each rendered and
parsed by a spec-compliant HTML parser. Not one forbidden element, attribute
or URL comes out. Every limit stops its runaway case. The browser bundle
renders the corpus to the same bytes as Node.

## API

| Export | What it does |
| - | - |
| `validateBlock({ template, stylesheet?, declaration? })` | The upload check: compile, stylesheet, sample render in Arabic, French and English. |
| `compileBlockTemplate(source, declaration?, options?)` | Checks a template and returns a reusable, frozen compiled template. `checks: 'syntax'` skips all but syntax. |
| `renderBlock(template, context, declaration?)` | Renders a source or a compiled template with one context: the gated HTML and its stats. |
| `renderCompiledBlock(template, context)` | The same, for a compiled template. |
| `validateBlockStylesheet(css, declaration?)` | Checks a stylesheet. |
| `sanitizeBlockHtml(html)` | The HTML gate every render goes through. |
| `resolveBlockSettings(settings, values)` | The setting values a block renders with: valid values, else defaults. |
| `blockCssVariables(settings, values)` | The `--block-<key>` CSS variables of colour settings, for the block's section. |
| `sampleBlockContext(declaration?, options?)` | A complete render context with sample data, for previews. |
| `imageUrl(url, width)` | What the `image_url` filter returns. |
| `linkKind(url)` | `external`, `store`, `fragment`, or null for a link blocks cannot have. |
| `isBlockImageSource(url)` | Whether an `<img src>` is one `image_url` makes. |
| `formatMoney(amount, currency, language)` | What the `money` filter returns. |
| `blockErrorFix(code)` | The default fix of a code. |
| `blockSettingVariable(key)` | The CSS variable of a colour setting. |

Constants: `BLOCK_LIMITS`, `BLOCK_ERROR_CODES`, `BLOCK_FILTERS`,
`BLOCK_HTML_ALLOWLIST`, `BLOCK_ROLES`, `BLOCK_NAMED_ENTITIES`,
`STOREFRONT_THEME_VARIABLES`, `BLOCK_PRODUCT_FIELDS`, `BLOCK_STORE_FIELDS`,
`BLOCK_FORLOOP_FIELDS`, `BLOCK_OBJECTS`, `BLOCK_DATA_OWNERS`,
`IMAGE_URL_WIDTHS`, `IMAGE_CDN_ORIGIN`, `RENDER_STEP_COSTS`,
`BLOCK_DIALECT_VERSION`.

## Checking it in real browsers

The specs run the browser bundle in an empty JavaScript context. To run it in
real engines (local, needs Chrome; macOS's JavaScriptCore when present):

```bash theme={null}
npm run build -w @tassyir/storefront-blocks
npm run browser-parity -w @tassyir/storefront-blocks
```

It renders the corpus from the built package in Node, headless Chrome and
JavaScriptCore, compares the bytes, and checks every rendered block with
Chrome's own HTML parser.


# @tassyir/ui
Source: https://developers.tassyir.io/packages/ui

Web components for Tassyir app pages: the dashboard's look (ink-on-paper tokens, right-to-left, dark mode) as custom elements that work in any framework or none.

Web components that make your app's page look like the
[Tassyir](https://tassyir.io) dashboard it runs in: ink on paper, hairline
borders, one cyan highlighter, Arabic right to left and English left to
right, light and dark. Assemble your page from these elements instead of
inventing styles, and it reads as part of the dashboard.

They are custom elements, so they work in any framework (React, Vue,
Svelte, Hono JSX) or none. Browser only, ESM only, no runtime dependency.
The package collects no analytics, uses no browser storage and makes no
network request. About 13.5 kB gzipped for every element.

## Install

```bash theme={null}
npm install @tassyir/ui @tassyir/app-bridge
```

## Example

Your manifest's `admin.page`, as plain HTML and TypeScript:

```html theme={null}
<!doctype html>
<html lang="en" dir="ltr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script type="module" src="/page.js"></script>
  </head>
  <body>
    <main>
      <tsy-page-header heading="Review requests">
        <span slot="meta">12 sent this week</span>
        <tsy-button slot="actions" variant="primary" id="send"
          >Send requests</tsy-button
        >
      </tsy-page-header>

      <tsy-banner tone="warning" heading="SMS credit is low" dismissible>
        120 messages left.
      </tsy-banner>

      <tsy-table heading="Pending orders" count="2">
        <table>
          <thead>
            <tr>
              <th>Order</th>
              <th data-align="end">Total</th>
              <th>Status</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>#00001042</td>
              <td data-align="end">9.000 دج</td>
              <td><tsy-status-pill tone="warning">Pending</tsy-status-pill></td>
            </tr>
          </tbody>
        </table>
      </tsy-table>

      <tsy-card heading="Settings">
        <form id="settings">
          <tsy-text-field
            name="sender"
            label="Sender name"
            hint="Shown at the top of the SMS."
            required
          ></tsy-text-field>
          <tsy-select name="delay" label="Send after" value="2">
            <option value="1">1 day</option>
            <option value="2">2 days</option>
          </tsy-select>
          <tsy-checkbox name="skipReturns" checked
            >Skip buyers who returned an order</tsy-checkbox
          >
          <tsy-button type="submit">Save</tsy-button>
        </form>
      </tsy-card>
    </main>
  </body>
</html>
```

```ts theme={null}
import { createAppBridge } from '@tassyir/app-bridge';
import { followDashboardContext } from '@tassyir/ui'; // also defines every element

const bridge = createAppBridge();

// The dashboard's language, direction and theme, on <html>, now and on
// every change. The elements and the tokens follow.
followDashboardContext(bridge);

document
  .querySelector<HTMLFormElement>('#settings')!
  .addEventListener('submit', async (event) => {
    event.preventDefault();
    const settings = Object.fromEntries(
      new FormData(event.currentTarget as HTMLFormElement),
    );
    // send `settings` to your server with a fresh ID token, then:
    await bridge.toast.show({ message: 'Settings saved', tone: 'success' });
  });
```

The fields submit with the `<form>` around them like native ones:
`new FormData(form)` holds `sender`, `delay` and `skipReturns`.

## The dashboard's rules

The elements keep DESIGN.md, the dashboard's design law. Your page keeps the
rest:

* **One ink button per view.** `variant="primary"` is the dashboard's dark
  call to action; put the view's one primary in the page header's actions.
  Everything else is `outline` (the default), `ghost` or `destructive`.
* **Status is a `<tsy-status-pill>`**, never a coloured word or a badge of
  your own.
* **No new colour.** Use the tokens (`var(--tsy-color-…)`), never a hex code.
  Cyan (`--tsy-color-brand-cyan`) is a highlighter: selection, progress,
  charts; never a button or a status.
* **14px is the floor** for any text, and type is the dashboard's sans.
* **Logical CSS only** (`margin-inline-start`, `padding-inline`,
  `text-align: start`), so the same rules serve Arabic and English.
* **Money and dates** read as the dashboard writes them: `9.000 دج` in
  Arabic, `DZD 9,000` in English; dates `yyyy-MM-dd` (`yyyy-MM-dd HH:mm`).
* **Modals, toasts, resource pickers, the save bar and the page title are
  not elements here.** They are App Bridge calls (`modal.open`, `toast.show`,
  `resource.pick`, `saveBar.show`, `titleBar.set`): the dashboard draws them,
  signed with your app's name. See
  [`@tassyir/app-bridge`](https://github.com/tassyir/apps-sdk/tree/main/packages/app-bridge#readme).

## Language, direction and theme

Your page runs in the dashboard's frame and cannot see its settings: App
Bridge sends them (`context.changed`: `locale`, `dir`, `theme`).
`followDashboardContext(bridge)` applies the current context at once and
every change after it, and returns the function that stops. It sets three
attributes on `<html>`:

* `lang`: `ar` or `en`. The elements' own words follow it ("Back",
  "Loading", "Dismiss", "(opens in a new tab)": Arabic for `ar`, English
  otherwise).
* `dir`: `rtl` or `ltr`. Every element is drawn with logical properties;
  arrows and carets mirror; arrow keys in a radio group follow the reading
  direction.
* `data-theme`: `light` or `dark`. The tokens switch, with `color-scheme`.

`applyDashboardContext({ locale, dir, theme }, root?)` sets them yourself,
for example in a page opened outside the dashboard. Light is the default. A
subtree with its own `data-theme` keeps that theme inside a page of the other
one.

The helpers take `@tassyir/app-bridge`'s bridge as it is but do not import
it: any object with `context.current` and `on('context.changed', …)` works.

## Elements

Importing `@tassyir/ui` defines every element (in a browser; on a server it
only exports, so server rendering can import it). An attribute that takes a
value ignores one it does not know and uses its default.

Frameworks: React 19, Vue, Svelte and Lit set a prop as a property when the
element has one and as an attribute otherwise; every property here that
shares an attribute's name (`value`, `checked`, `form`, `prefix`, `type`, …)
takes the attribute's value, so the markup above works as written. Events
are DOM events (`input`, `change`, `tsy-dismiss`): where a framework does
not bind them, add a listener with `addEventListener` (in React, through a
ref).

### `<tsy-button>`

The dashboard's button: 36px, 12px corners, a 14px medium label.

```html theme={null}
<tsy-button variant="primary" type="submit">Save</tsy-button>
<tsy-button href="/settings">Settings</tsy-button>
<tsy-button square aria-label="More actions">⋯</tsy-button>
```

| Attribute | Values | Meaning |
| - | - | - |
| `variant` | `outline` (default), `primary`, `ghost`, `destructive` | `primary` is the ink button, one per view. |
| `size` | `md` (default, 36px), `sm` (32px), `lg` (40px) | |
| `type` | `button` (default), `submit`, `reset` | `submit` submits the form around it, `reset` resets it. |
| `disabled` | boolean | Dimmed, out of the tab order, clicks swallowed. |
| `loading` | boolean | A spinner before the label; stays focusable, `aria-busy`, clicks swallowed. |
| `href` | URL | A link that looks like a button. `target`, `rel` and `download` pass through. |
| `target`, `rel`, `download` | as on `<a>` | With `href` only. |
| `full-width` | boolean | Fills its container's width. |
| `square` | boolean | As wide as it is high, for one glyph. Give it an `aria-label`. |

`aria-label`, `aria-pressed` and `aria-expanded` are passed to the inner
control. A submit or reset acts after every `click` listener ran, unless one
called `preventDefault()`. Slot: the label (a 16px `<svg>` may sit beside it).

### `<tsy-link>`

An underlined link in the colour of the text around it, ink on hover.

```html theme={null}
Questions?
<tsy-link href="https://developers.tassyir.io" external>Read the guide</tsy-link
>.
```

| Attribute | Values | Meaning |
| - | - | - |
| `href` | URL | The address. |
| `external` | boolean | Opens in a new tab with `rel="noopener noreferrer"`, shows ↗ and says so to screen readers. |
| `target`, `rel`, `download` | as on `<a>` | |

`aria-label` passes to the inner `<a>`. In the dashboard, your app moving to
another of its pages is `bridge.navigate({ path })`; leaving for a dashboard
page is `bridge.navigate({ dashboard })`.

### `<tsy-text-field>`

A labelled input, or a text area with `multiline`.

```html theme={null}
<tsy-text-field
  name="minimum"
  type="number"
  label="Minimum order total"
  suffix="DZD"
  hint="Orders below it get no request."
></tsy-text-field>
```

| Attribute | Values | Meaning |
| - | - | - |
| `label` | text | The field's label. Always give one. |
| `label-hidden` | boolean | Keeps the label for screen readers only (a search box). |
| `name` | text | The form field's name. |
| `value` | text | The default value; the `value` property is the current one. |
| `type` | `text` (default), `email`, `number`, `password`, `search`, `tel`, `url` | `email`, `password`, `tel` and `url` are typed left to right in an Arabic page too. |
| `hint` | text | A muted line under the field. |
| `error` | text | The field's error, in red under it; marks the field invalid for assistive technology. |
| `prefix`, `suffix` | text | A short unit inside the field, such as `DZD` or `دج`. |
| `required`, `disabled`, `readonly` | boolean | |
| `multiline` | boolean | A text area. |
| `rows` | number | With `multiline`. |
| `placeholder`, `autocomplete`, `inputmode`, `minlength`, `maxlength`, `min`, `max`, `step`, `pattern`, `spellcheck`, `enterkeyhint` | as on `<input>` | Passed to the inner control. |

Properties: `value`, `form`, `validity`, `validationMessage`; methods
`select()`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`.
Events: `input` and `change`, from the element.

### `<tsy-select>`

A labelled native select: on a phone, the phone's own picker opens. Write
its `<option>` and `<optgroup>` elements inside it.

```html theme={null}
<tsy-select name="wilaya" label="Wilaya" placeholder="All wilayas">
  <option value="16">16 · Alger</option>
  <option value="31">31 · Oran</option>
</tsy-select>
```

| Attribute | Values | Meaning |
| - | - | - |
| `label`, `label-hidden` | | As on `<tsy-text-field>`. |
| `name` | text | The form field's name. |
| `value` | text | The default choice; else the `selected` option, else the first one. |
| `placeholder` | text | An empty first choice that cannot be picked back; `required` refuses it. |
| `hint`, `error` | text | As on `<tsy-text-field>`. |
| `required`, `disabled` | boolean | |
| `autocomplete` | as on `<select>` | |

The options are mirrored into the inner select whenever they change.
Properties: `value`, `options`, `selectedIndex`, `form`, `validity`. Events:
`input`, `change`.

### `<tsy-checkbox>`

A checkbox with its label as content.

```html theme={null}
<tsy-checkbox name="notify" checked>Notify the buyer</tsy-checkbox>
```

| Attribute | Values | Meaning |
| - | - | - |
| `name` | text | The form field's name. |
| `checked` | boolean | Checked by default; the `checked` property is the current state. |
| `value` | text (`on`) | What it submits while checked. |
| `indeterminate` | boolean | Neither (a "select all" over part of a list); cleared by a click. |
| `hint`, `error` | text | Under the label. |
| `required`, `disabled` | boolean | |

`aria-label` names a checkbox without content (a table's row selection).
Events: `input`, `change`.

### `<tsy-radio-group>` and `<tsy-radio>`

A labelled set of choices. Arrow keys move and choose (mirrored right to
left); the group is one Tab stop.

```html theme={null}
<tsy-radio-group name="channel" label="Channel" value="sms">
  <tsy-radio value="sms">SMS</tsy-radio>
  <tsy-radio value="whatsapp" hint="Needs a connected number"
    >WhatsApp</tsy-radio
  >
  <tsy-radio value="email" disabled>Email</tsy-radio>
</tsy-radio-group>
```

`<tsy-radio-group>`:

| Attribute | Values | Meaning |
| - | - | - |
| `label` | text | The group's label. |
| `name` | text | The form field's name. |
| `value` | text | The default choice; `value` property: current. |
| `hint`, `error` | text | Under the choices. |
| `required`, `disabled` | boolean | `required` refuses an empty choice. |
| `orientation` | `vertical` (default), `horizontal` | Choices in a column, or in a wrapping row. |

`<tsy-radio>`:

| Attribute | Values | Meaning |
| - | - | - |
| `value` | text | What the group submits when this one is chosen. |
| `hint` | text | A muted line under the label. |
| `disabled` | boolean | Cannot be chosen, skipped by the arrow keys. |

Events (from the group): `input`, `change`. Methods: `checkValidity()`,
`reportValidity()`, `setCustomValidity()`, `focus()` (the chosen radio, or
the first). A radio added or removed later is taken into account: a removed
choice clears the value.

### `<tsy-card>`

The dashboard's content card. With a `heading` it is the layered card: a
tinted header bar with the title in the quiet label style, an optional
count, actions at the end, over a paper body. Without, a plain paper card.

```html theme={null}
<tsy-card heading="Answers" count="4">
  <tsy-button slot="actions" variant="ghost" size="sm">Export</tsy-button>
  …
</tsy-card>
```

| Attribute | Values | Meaning |
| - | - | - |
| `heading` | text | The card's title. |
| `heading-level` | `2` (default) to `6` | The title is an `<h2>` unless you say otherwise. |
| `count` | text | A count chip beside the title. |
| `flush` | boolean | No padding in the body (a list or a table edge to edge). |

Slots: the body; `actions`. Never put a card inside a card.

### `<tsy-page-header>`

The page's title, its one `<h1>`, with an optional back link, a muted line
of facts and the page's actions.

```html theme={null}
<tsy-page-header heading="Order #00001042" back-href="/orders">
  <span slot="meta">Sara Bensalem · Oran</span>
  <tsy-button slot="actions" variant="primary">Confirm</tsy-button>
</tsy-page-header>
```

| Attribute | Values | Meaning |
| - | - | - |
| `heading` | text | The page's title (24px; 22px right to left). |
| `back-href` | URL | Shows a back link above the title. |
| `back-label` | text | The back link's words (default "Back", Arabic «رجوع»). |

Slots: `meta`, `actions`. The dashboard's title bar already shows your app's
name; `bridge.titleBar.set({ title })` adds the page's title beside it.

### `<tsy-table>`

The dashboard's table frame around a native `<table>` you write inside it:
a tinted frame, an optional header bar, a toolbar strip, the rows as a paper
panel that scrolls sideways on a phone, and a footer. The table keeps its
native semantics.

```html theme={null}
<tsy-table heading="Orders" count="128">
  <tsy-text-field
    slot="toolbar"
    type="search"
    label="Search orders"
    label-hidden
  ></tsy-text-field>
  <table>
    <thead>
      <tr>
        <th>Order</th>
        <th data-align="end">Total</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>#00001042</td>
        <td data-align="end">DZD 9,000</td>
      </tr>
    </tbody>
  </table>
  <div slot="footer">1–20 of 128</div>
</tsy-table>
```

| Attribute | Values | Meaning |
| - | - | - |
| `heading` | text | The frame's title; also the table's name for screen readers, unless it has a caption, `aria-label` or `aria-labelledby`. |
| `heading-level` | `2` (default) to `6` | |
| `count` | text | A count chip beside the title. |
| `density` | `compact` (default), `comfortable` | Roomier rows. |

Slots: the `<table>`; `actions`, `toolbar`, `footer`. On cells:
`data-align="end"` aligns a number to the end, `data-wrap` lets a cell wrap.
A row with `aria-selected="true"` is tinted. The table's styles are adopted
into the document (or the shadow root it lives in), in the `tassyir-ui`
cascade layer.

### `<tsy-status-pill>`

The dashboard's only status treatment: a dot, a 12% tint of the tone, the
words in the tone pushed toward ink.

```html theme={null}
<tsy-status-pill tone="success">Delivered</tsy-status-pill>
<tsy-status-pill color="#e11d48">Called twice</tsy-status-pill>
```

| Attribute | Values | Meaning |
| - | - | - |
| `tone` | `neutral` (default), `success`, `warning`, `destructive`, `info`, `purple` | The semantic hue. |
| `color` | a CSS colour | A merchant's own status colour, mixed the same way; overrides `tone`. |
| `size` | `sm` (default), `md` | |
| `hide-dot` | boolean | No dot. |

Slot `icon`: a 16px glyph in place of the dot (a lock, say).

### `<tsy-banner>`

A quiet tinted notice: a glyph, an optional heading, the message and
actions.

```html theme={null}
<tsy-banner tone="critical" heading="Could not reach 2 buyers">
  The carrier refused their phone numbers.
  <tsy-button slot="actions" size="sm">See who</tsy-button>
</tsy-banner>
```

| Attribute | Values | Meaning |
| - | - | - |
| `tone` | `info` (default), `success`, `warning`, `critical` | `warning` and `critical` are announced (`role="alert"`), the others politely (`role="status"`). |
| `heading` | text | A bold first line. |
| `dismissible` | boolean | A close button. |

Slots: the message; `actions`. Closing fires `tsy-dismiss` (bubbles,
cancelable); unless a listener prevents it, the banner hides. `dismiss()`
does the same from code. A passing confirmation ("Saved") is a toast:
`bridge.toast.show`.

### `<tsy-empty-state>`

What a list says when it has nothing yet. Keep it for a surface with
something to teach; in a form, a plain button says more.

```html theme={null}
<tsy-empty-state heading="No answers yet">
  Answers appear here once buyers reply.
  <tsy-button slot="actions">Send a test request</tsy-button>
</tsy-empty-state>
```

| Attribute | Values | Meaning |
| - | - | - |
| `heading` | text | The title. |
| `heading-level` | `1` to `6` | Makes the title a heading for assistive technology (it is not, by default). |

Slots: `media` (a glyph), the sentence, `actions`.

### `<tsy-skeleton>`

A loading placeholder in the shape of what is coming. The dashboard shows
skeletons, not spinners, while a page or a card loads.

```html theme={null}
<tsy-card heading="Orders" aria-busy="true">
  <tsy-skeleton lines="3"></tsy-skeleton>
</tsy-card>
```

| Attribute | Values | Meaning |
| - | - | - |
| `shape` | `line` (default), `block`, `circle` | |
| `lines` | number (1 to 20) | Lines of text, the last one shorter (`line` only). |
| `width` | a CSS length (a number is pixels) | |
| `height` | a CSS length (a number is pixels) | |

It is hidden from assistive technology; mark the region it stands in
`aria-busy="true"` and clear it when the content arrives. The pulse stops
under reduced motion.

### `<tsy-spinner>`

In-place loading: a button, a row.

```html theme={null}
<tsy-spinner size="sm" label="Loading orders"></tsy-spinner>
```

| Attribute | Values | Meaning |
| - | - | - |
| `size` | `md` (default, 24px), `sm` (16px), `lg` (32px) | |
| `label` | text | What screen readers hear (default "Loading", in the page's language). |

## Forms

`<tsy-text-field>`, `<tsy-select>`, `<tsy-checkbox>`, `<tsy-radio-group>` and
`<tsy-button>` are form-associated custom elements: they submit with the
native `<form>` around them (`FormData`, a normal submit), take part in its
validation (`required`, the input's own constraints, `setCustomValidity`),
are reset with it and follow a disabled `<fieldset>`. Enter in a one-line
field does what it does in a native one: it clicks the form's first submit
button (nothing happens while that button is disabled or `loading`, so a
save in flight is not sent twice); with no submit button, it submits a form
that has only that one field.

* Label every field with its `label` attribute. A `<label for>` outside the
  element does not reach the input inside it.
* `error` shows a message and marks the field invalid for assistive
  technology, but does not block the form: it is for your server's answer.
  To block, call `setCustomValidity(message)`.
* In the dashboard, saving a form the merchant edits is the dashboard's save
  bar: `bridge.saveBar.show()` and its `saveBar.save` / `saveBar.discard`
  events.

## Tokens

Importing the package adopts the tokens into the document. Use them in your
own CSS:

```css theme={null}
.summary {
  padding: var(--tsy-space-grid);
  border: 1px solid var(--tsy-color-hairline);
  border-radius: var(--tsy-radius-control);
  color: var(--tsy-color-ink-secondary);
}
```

* Colours, both themes: `--tsy-color-ink`, `-ink-secondary`, `-ink-tertiary`,
  `-paper`, `-paper-sunken`, `-muted-fill`, `-accent-fill`, `-hairline`,
  `-field`, `-on-ink`, `-skeleton`, `-brand-cyan`, `-success`,
  `-success-soft`, `-warning`, `-warning-ink`, `-warning-soft`, `-info`,
  `-info-soft`, `-destructive`, `-destructive-on`, `-destructive-soft`,
  `-purple`, `-pill-surface`, `-pill-ink`, `-control-hover`, `-ghost-hover`,
  `-destructive-fill`; shadows `--tsy-shadow-paper`, `--tsy-shadow-control`.
* Type: `--tsy-font-sans`, `--tsy-font-mono`; sizes `--tsy-font-size-body`,
  `-label` (14px), `-title` (18px), `-headline` (20px), `-page-title` (24px),
  `-page-title-rtl` (22px); weights `--tsy-font-weight-regular` (400),
  `-medium` (500), `-semibold` (600), `-bold` (700, the page title only);
  `--tsy-line-height-*`.
* Space: `--tsy-space-hint` (6px), `-hug` (8px), `-cluster` (12px), `-grid`
  (16px), `-section` (24px). Radii: `--tsy-radius-control` (12px), `-nested`
  (8px), `-pill`.

The same values are data in `@tassyir/ui/tokens` (no DOM, safe on a server:
`colors.dark.ink`, `breakpoints.sm`, …) and a stylesheet in
`@tassyir/ui/tokens.css` for a page that wants the tokens without the
elements. They sit in the `tassyir-ui` cascade layer, with the page's
defaults (paper background, ink text, the Tassyir type, 14px body) at zero
specificity, so any rule of yours that is not in a layer wins.

If your CSS uses cascade layers (Tailwind v4 does), name ours first, at the
very top of your stylesheet: layers declared first lose to the ones after,
and the package adds its sheet after yours.

```css theme={null}
@layer tassyir-ui;
@import 'tailwindcss';
```

## Fonts

The dashboard sets Geist (Latin) and IBM Plex Sans Arabic. This package loads
no font, so nothing leaves your page; the type falls back to the system's
sans. To show the exact faces, serve them yourself (both are under the SIL
Open Font License) under those family names:

```css theme={null}
@font-face {
  font-family: 'Geist';
  src: url('/fonts/geist.woff2') format('woff2');
  font-weight: 100 900;
}
@font-face {
  font-family: 'IBM Plex Sans Arabic';
  src: url('/fonts/ibm-plex-sans-arabic-500.woff2') format('woff2');
  font-weight: 500;
}
```

## Styling

Every element draws in its own shadow root, so your CSS cannot break it by
accident, and the tokens reach inside. To adjust one, style the element
itself (`tsy-card { margin-block: 24px }`) or a part:
`tsy-text-field::part(box)`. Parts: `base`, `control`, `label`, `hint`,
`error`, `box`, `prefix`, `suffix`, `row`, `heading`, `count`, `actions`,
`body`, `header`, `meta`, `back`, `toolbar`, `footer`, `scroll`, `dot`,
`media`, `dismiss`, `bar`, `link`, `options`. To hide elements until they
are defined, add `:not(:defined) { visibility: hidden }`.

## Accessibility

Built in: a label on every field, its hint and error read with it, a
visible focus ring on every control, the arrow-key radio group, a 32px close
button, live regions for banners and spinners, text pairs measured at 4.5:1
or more in both themes (a spec measures every pair the elements paint), and
motion stopped or slowed under `prefers-reduced-motion`. Your page's part:
the one `<h1>` is `<tsy-page-header>`'s; give icon-only buttons an
`aria-label`; mark loading regions `aria-busy`.

## Content-Security-Policy, Trusted Types, server rendering

The elements write no `<style>` element and no `style` attribute (styles are
constructable stylesheets; colours set through the CSSOM) and never assign
HTML (`createElement` only). A page served with `style-src 'self'`,
`script-src 'self'` and `require-trusted-types-for 'script'` works; the demo
is served that way. Importing the package on a server defines nothing and
throws nothing.

## Size

Minified and gzipped, as an app's bundler ships it (`npm run size -w @tassyir/ui`):

| Import | Minified | Gzipped |
| - | - | - |
| everything (`@tassyir/ui`) | 52.7 kB | 13.5 kB |
| the shared core (base class, tokens) | 5.0 kB | 2.0 kB |
| `tsy-button` alone, with the core | 12.7 kB | 4.5 kB |
| `tsy-link` alone, with the core | 8.3 kB | 3.4 kB |
| `tsy-text-field` alone, with the core | 13.0 kB | 4.6 kB |
| `tsy-select` alone, with the core | 17.4 kB | 5.7 kB |
| `tsy-checkbox` alone, with the core | 12.3 kB | 4.5 kB |
| `tsy-radio-group` + `tsy-radio`, with the core | 13.8 kB | 5.0 kB |
| `tsy-card` alone, with the core | 7.7 kB | 2.8 kB |
| `tsy-page-header` alone, with the core | 9.4 kB | 3.7 kB |
| `tsy-table` alone, with the core | 10.9 kB | 3.6 kB |
| `tsy-status-pill` alone, with the core | 7.1 kB | 2.8 kB |
| `tsy-banner` alone, with the core | 10.1 kB | 3.9 kB |
| `tsy-empty-state` alone, with the core | 7.1 kB | 2.7 kB |
| `tsy-skeleton` alone, with the core | 6.6 kB | 2.7 kB |
| `tsy-spinner` alone, with the core | 7.6 kB | 3.2 kB |

Most of it is CSS. The package is one entry today (`import '@tassyir/ui'`
defines every element).

## Checking against the dashboard

`src/frontend-parity.test.ts` compares this package with the dashboard's own
design in the private `tassyir/frontend` repository: every colour token
against the palette blocks of `app/[locale]/globals.css`, string for string
in both themes; DESIGN.md's front matter (colours, radii, spacing, type, the
button, input and card); and the classes of the dashboard's primitives each
element mirrors. CI cannot reach that repository, so it runs locally:

```bash theme={null}
TASSYIR_FRONTEND_DIR=../frontend npm run parity -w @tassyir/ui
```

It reads `origin/main` (or `TASSYIR_FRONTEND_REF`) with `git show`; run
`git -C ../frontend fetch origin` first.

`npm run browser-check -w @tassyir/ui` (after `npm run build`) runs the demo
in a headless Chrome under a strict Content-Security-Policy: real form
submission and validity, the keyboard, the accessibility tree, and the demo
in Arabic and English, light and dark, at 390 and 1440 px, with a screenshot
of each (`--out <dir>`). `npm run demo -w @tassyir/ui` serves the demo at
[http://localhost:4178/demo/](http://localhost:4178/demo/).

## Not here yet

React and JSX typings for the elements, a `custom-elements.json` manifest
for editors, per-element entry points, and more elements (tabs, a stat card,
a popover) come in later releases.