API client
Call the Storeware API for one shop, with tokens that refresh themselves.
import { ... } from '@storeware/plugin-sdk';StorewareApiError
new StorewareApiError(status: number, type: string, message: string, requiredScopes?: string[] | undefined)StorewareClient
new StorewareClient(options: StorewareClientOptions)| Name | Type | Description |
|---|---|---|
get | <T>(path: string) => Promise<T> | |
post | <T>(path: string, body?: unknown) => Promise<T> | |
patch | <T>(path: string, body?: unknown) => Promise<T> | |
put | <T>(path: string, body?: unknown) => Promise<T> | |
delete | <T>(path: string, body?: unknown) => Promise<T> | A body is rare on a delete, and cancelOrder is the one call that takes one. |
billing | AppBilling | What this shop pays your app. Ask for a plan or a one-time charge, then send the merchant to its confirmationUrl; nothing is owed until they approve. See https://storeware.ai/docs/selling/billing. |
settings | () => Promise<AppSettingsState> | What the merchant set for your app on this shop, as your installed release's [[settings]] declares it. You hear of a change as app.settings_updated.v1. See https://storeware.ai/docs/extensions/settings. |
uploadAsset | (input: { data: Uint8Array | ArrayBuffer | string; contentType: AppAssetContentType; }) => Promise<UploadedAppAsset> | Puts a picture on Storeware for your components, and gives its address. PNG, JPEG, WebP, GIF or AVIF, at most 5 MB. data is the bytes, or a base64 string of them. Needs no permission. |
StorewareClientOptions
type StorewareClientOptions = (BaseOptions & {
refreshToken?: undefined;
}) | (BaseOptions & {
refreshToken: string;
clientId: string;
clientSecret: string;
onTokensRefreshed: (tokens: StorewareTokens) => void | Promise<void>;
});QuotedPrices
Prices in every currency Storeware quotes, in minor units. Nothing is converted.
| Name | Type | Description |
|---|---|---|
usd | number | |
gbp | number | |
eur | number | |
inr | number |
AppSubscription
| Name | Type | Description |
|---|---|---|
id | string | |
plan | string | |
name | string | |
status | | 'pending' | 'active' | 'past_due' | 'frozen' | 'scheduled' | 'canceled' | 'declined' | 'expired' | |
amountMinor | number | |
currency | 'usd' | 'gbp' | 'eur' | 'inr' | |
interval | 'month' | 'year' | |
test | boolean | |
trialEndsAt | string | null | |
currentPeriodStart | string | null | |
currentPeriodEnd | string | null | |
cancelAtPeriodEnd | boolean | |
createdAt | string | |
confirmationUrl | string | null | Where to send the merchant while it waits for their answer. |
usageCapMinor | number | null | The most a period's usage may come to, for a plan that charges by use. |
usageTerms | string | null |
AppUsage
A period's usage on the plan in force.
| Name | Type | Description |
|---|---|---|
capMinor | number | |
usedMinor | number | |
terms | string | null |
AppPurchase
| Name | Type | Description |
|---|---|---|
id | string | |
name | string | |
amountMinor | number | |
currency | 'usd' | 'gbp' | 'eur' | 'inr' | |
test | boolean | |
status | 'pending' | 'accepted' | 'declined' | 'expired' | |
createdAt | string | |
confirmationUrl | string | null |
AppBillingState
| Name | Type | Description |
|---|---|---|
currency | 'usd' | 'gbp' | 'eur' | 'inr' | |
subscription | AppSubscription | null | |
usage | AppUsage | null | |
scheduled | AppSubscription | null | |
pending | { subscriptions: AppSubscription[]; purchases: AppPurchase[] } | |
purchases | AppPurchase[] | |
plans | { key: string; name: string; interval: 'month' | 'year'; amountMinor: number; trialDays: number; }[] |
AppBilling
| Name | Type | Description |
|---|---|---|
state | () => Promise<AppBillingState> | |
requestSubscription | (input: { plan: string; returnUrl: string; test?: boolean; idempotencyKey?: string; }) => Promise<AppSubscription> | |
requestPurchase | (input: { name: string; prices: QuotedPrices; returnUrl: string; test?: boolean; idempotencyKey?: string; }) => Promise<AppPurchase> | |
cancelSubscription | (id: string) => Promise<AppSubscription> | |
recordUsage | (input: { amountMinor: number; description: string; idempotencyKey?: string; }) => Promise<{ id: string; amountMinor: number; usage: AppUsage; }> | What the shop used, in the plan's currency. Refused (402) past the period's cap. |
credit | (input: { amountMinor: number; description: string; idempotencyKey?: string; }) => Promise<{ id: string; amountMinor: number; currency: string; }> | A credit on the shop's next statement, in its billing currency. |
AppSettingsState
What client.settings() answers with.
| Name | Type | Description |
|---|---|---|
values | Record<string, string | number | boolean | null> | Every field your installed release declares in [[settings]], by key: what the merchant saved, else its default, else null. Secrets in the clear. |
updatedAt | string | null | ISO, or null when the merchant has never saved. |
AppAssetContentType
The pictures client.uploadAsset() takes. Checked by their bytes, so say what they are.
type AppAssetContentType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | 'image/avif';UploadedAppAsset
| Name | Type | Description |
|---|---|---|
url | string | On cdn.mystoreware.com, the one host an image in your components may come from. |
contentType | AppAssetContentType | |
sizeBytes | number | |
sha256 | string |