@inferencebureau/apps-sdk 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -74,12 +74,15 @@ with a key linked to the app.
74
74
  Entry points:
75
75
 
76
76
  - `@inferencebureau/apps-sdk`: metadata types, action helpers, `createClient`, `createShopifyClient`,
77
- `verifyShopifySession`, `verifyProxyRequest`, and the errors they throw (`ApiError`, `ShopifyError`).
77
+ `verifyShopifySession`, `verifyProxyRequest`, Shopify Billing for public apps (`requestSubscription`,
78
+ `activeSubscriptions`, `recordUsage`, `cancelSubscription`, `managedPricingUrl`), and the errors they throw
79
+ (`ApiError`, `ShopifyError`, `ShopifyBillingError`).
78
80
  - `@inferencebureau/apps-sdk/runtime`: `handleAction`, the signed `/_ib/actions` route every build adds.
79
81
  - `@inferencebureau/apps-sdk/browser`: for an embedded admin page's client code: `sessionFetch`,
80
82
  `shopifySessionToken`, `isPreview`, `previewSession`.
81
83
  - `@inferencebureau/apps-sdk/test`: for the app's tests: `loadApp` (or `createTestApp`) runs actions against
82
84
  in-memory records with the records engine's rules, mocks the Shopify Admin API, delivers webhooks and installs,
83
- and runs queued jobs; `fixtures` has Shopify's webhook payloads. Node only.
85
+ and runs queued jobs; `fixtures` has Shopify's webhook payloads. Node only, under Vitest with this package inlined:
86
+ `test: { server: { deps: { inline: ["@inferencebureau/apps-sdk"] } } }` in vitest.config.ts (new apps have it).
84
87
 
85
88
  Docs: https://app.inferencebureau.com/docs/apps
package/dist/index.d.ts CHANGED
@@ -230,6 +230,8 @@ export declare function createClient(o?: ClientOptions): Api;
230
230
  */
231
231
  export interface ShopifyClient {
232
232
  shop: string;
233
+ /** The environment the client calls from (IB_ENVIRONMENT): Billing makes test charges outside production. */
234
+ environment?: string;
233
235
  /** Runs an Admin GraphQL query or mutation and returns its `data`; GraphQL errors throw ShopifyError. */
234
236
  graphql<T = any>(query: string, variables?: Record<string, unknown>): Promise<T>;
235
237
  }
@@ -239,6 +241,103 @@ export declare class ShopifyError extends Error {
239
241
  }
240
242
  /** The Admin API for `shop`, as the environment (the same options as createClient). */
241
243
  export declare function createShopifyClient(shop: string, o?: ClientOptions): ShopifyClient;
244
+ export interface Money {
245
+ amount: number | string;
246
+ currencyCode: string;
247
+ }
248
+ export interface SubscriptionRequest {
249
+ /** What the merchant sees on Shopify's approval page and their bill. */
250
+ name: string;
251
+ /** Where Shopify sends the merchant after they approve or decline (an embedded page of the app). */
252
+ returnUrl: string;
253
+ /** A fixed charge each period. */
254
+ recurring?: {
255
+ price: Money;
256
+ interval?: "EVERY_30_DAYS" | "ANNUAL";
257
+ };
258
+ /** Usage charges up to a cap each 30 days, recorded with `recordUsage`. `terms` is shown to the merchant. */
259
+ usage?: {
260
+ cappedAmount: Money;
261
+ terms: string;
262
+ };
263
+ trialDays?: number;
264
+ /** What happens to an active subscription: by default Shopify decides (upgrade now, downgrade at period end). */
265
+ replacementBehavior?: "APPLY_IMMEDIATELY" | "APPLY_ON_NEXT_BILLING_CYCLE" | "STANDARD";
266
+ /** Force a test charge, or (in production on a real store only) a real one. */
267
+ test?: boolean;
268
+ }
269
+ export interface AppSubscription {
270
+ id: string;
271
+ name: string;
272
+ status: string;
273
+ test: boolean;
274
+ trialDays: number;
275
+ currentPeriodEnd: string | null;
276
+ createdAt: string;
277
+ lineItems: {
278
+ id: string;
279
+ recurring?: {
280
+ price: Money;
281
+ interval: string;
282
+ };
283
+ usage?: {
284
+ cappedAmount: Money;
285
+ balanceUsed: Money;
286
+ terms: string;
287
+ };
288
+ }[];
289
+ }
290
+ export declare class ShopifyBillingError extends Error {
291
+ readonly userErrors: {
292
+ field?: string[] | null;
293
+ message: string;
294
+ }[];
295
+ constructor(message: string, userErrors?: {
296
+ field?: string[] | null;
297
+ message: string;
298
+ }[]);
299
+ }
300
+ /**
301
+ * Whether a charge for this store is a test charge: always outside production, and in production on a development
302
+ * store (Shopify's `partnerDevelopment` plan), unless `test` says otherwise.
303
+ */
304
+ export declare function isTestCharge(shopify: ShopifyClient, test?: boolean): Promise<boolean>;
305
+ /**
306
+ * Starts a subscription and returns Shopify's `confirmationUrl`: redirect the merchant there (from an embedded page,
307
+ * open it at the top level) to approve. It's active once they do: `activeSubscriptions` or the synced model says so.
308
+ */
309
+ export declare function requestSubscription(shopify: ShopifyClient, plan: SubscriptionRequest): Promise<{
310
+ confirmationUrl: string;
311
+ subscriptionId: string;
312
+ test: boolean;
313
+ }>;
314
+ /** The store's active subscriptions to this app (usually one), with each line's price or usage cap and balance. */
315
+ export declare function activeSubscriptions(shopify: ShopifyClient): Promise<AppSubscription[]>;
316
+ /**
317
+ * Charges usage on a subscription's usage line: the active one's unless `lineItemId` names another. Pass an
318
+ * `idempotencyKey` (an order id, a job id) so a retried action doesn't charge twice. Shopify refuses a charge past
319
+ * the line's cap; raise it with a new subscription (`replacementBehavior: "APPLY_IMMEDIATELY"`).
320
+ */
321
+ export declare function recordUsage(shopify: ShopifyClient, charge: {
322
+ price: Money;
323
+ description: string;
324
+ idempotencyKey?: string;
325
+ lineItemId?: string;
326
+ }): Promise<{
327
+ id: string;
328
+ }>;
329
+ /** Cancels a subscription; `prorate` refunds the unused part of the period. */
330
+ export declare function cancelSubscription(shopify: ShopifyClient, id: string, o?: {
331
+ prorate?: boolean;
332
+ }): Promise<{
333
+ id: string;
334
+ status: string;
335
+ }>;
336
+ /**
337
+ * Shopify's plan page for an app on managed pricing (plans set in the Partner Dashboard): where to send a merchant
338
+ * to pick or change their plan. `appHandle` is the app's handle in the Partner Dashboard.
339
+ */
340
+ export declare function managedPricingUrl(shop: string, appHandle: string): string;
242
341
  export interface ShopifySession {
243
342
  /** The store the admin page is open in (x.myshopify.com). */
244
343
  shop: string;
package/dist/index.js CHANGED
@@ -152,6 +152,7 @@ export function createShopifyClient(shop, o = {}) {
152
152
  const f = o.fetch ?? fetch;
153
153
  return {
154
154
  shop,
155
+ environment,
155
156
  async graphql(query, variables = {}) {
156
157
  const res = await f(`${url}/v1/apps/${encodeURIComponent(app)}/environments/${encodeURIComponent(environment)}/shopify/graphql`, {
157
158
  method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ shop, query, variables }),
@@ -165,6 +166,102 @@ export function createShopifyClient(shop, o = {}) {
165
166
  },
166
167
  };
167
168
  }
169
+ export class ShopifyBillingError extends Error {
170
+ userErrors;
171
+ constructor(message, userErrors = []) {
172
+ super(message);
173
+ this.userErrors = userErrors;
174
+ }
175
+ }
176
+ const money = (m) => ({ amount: Number(m.amount), currencyCode: m.currencyCode });
177
+ const userErrorsOf = (what, errors) => {
178
+ if (errors?.length)
179
+ throw new ShopifyBillingError(`Shopify didn't ${what}: ${errors.map((e) => e.message).join("; ")}`, errors);
180
+ };
181
+ /**
182
+ * Whether a charge for this store is a test charge: always outside production, and in production on a development
183
+ * store (Shopify's `partnerDevelopment` plan), unless `test` says otherwise.
184
+ */
185
+ export async function isTestCharge(shopify, test) {
186
+ if ((shopify.environment ?? "development") !== "production")
187
+ return true;
188
+ if (test !== undefined)
189
+ return test;
190
+ const data = await shopify.graphql(`query BillingShopPlan { shop { plan { partnerDevelopment } } }`);
191
+ return data.shop.plan.partnerDevelopment;
192
+ }
193
+ /**
194
+ * Starts a subscription and returns Shopify's `confirmationUrl`: redirect the merchant there (from an embedded page,
195
+ * open it at the top level) to approve. It's active once they do: `activeSubscriptions` or the synced model says so.
196
+ */
197
+ export async function requestSubscription(shopify, plan) {
198
+ if (!plan.recurring && !plan.usage)
199
+ throw new ShopifyBillingError("A subscription needs a recurring price, usage charges, or both.");
200
+ const lineItems = [
201
+ ...(plan.recurring ? [{ plan: { appRecurringPricingDetails: { price: money(plan.recurring.price), interval: plan.recurring.interval ?? "EVERY_30_DAYS" } } }] : []),
202
+ ...(plan.usage ? [{ plan: { appUsagePricingDetails: { cappedAmount: money(plan.usage.cappedAmount), terms: plan.usage.terms } } }] : []),
203
+ ];
204
+ const test = await isTestCharge(shopify, plan.test);
205
+ const data = await shopify.graphql(`
206
+ mutation BillingSubscribe($name: String!, $lineItems: [AppSubscriptionLineItemInput!]!, $returnUrl: URL!, $trialDays: Int, $test: Boolean, $replacementBehavior: AppSubscriptionReplacementBehavior) {
207
+ appSubscriptionCreate(name: $name, lineItems: $lineItems, returnUrl: $returnUrl, trialDays: $trialDays, test: $test, replacementBehavior: $replacementBehavior) {
208
+ confirmationUrl appSubscription { id } userErrors { field message }
209
+ }
210
+ }`, { name: plan.name, lineItems, returnUrl: plan.returnUrl, trialDays: plan.trialDays ?? null, test, replacementBehavior: plan.replacementBehavior ?? null });
211
+ userErrorsOf("start the subscription", data.appSubscriptionCreate.userErrors);
212
+ if (!data.appSubscriptionCreate.confirmationUrl || !data.appSubscriptionCreate.appSubscription)
213
+ throw new ShopifyBillingError("Shopify didn't return a confirmation URL.");
214
+ return { confirmationUrl: data.appSubscriptionCreate.confirmationUrl, subscriptionId: data.appSubscriptionCreate.appSubscription.id, test };
215
+ }
216
+ const SUBSCRIPTION = `id name status test trialDays currentPeriodEnd createdAt
217
+ lineItems { id plan { pricingDetails { __typename
218
+ ... on AppRecurringPricing { price { amount currencyCode } interval }
219
+ ... on AppUsagePricing { cappedAmount { amount currencyCode } balanceUsed { amount currencyCode } terms } } } }`;
220
+ const subscriptionOf = (s) => ({
221
+ ...s,
222
+ lineItems: s.lineItems.map((l) => {
223
+ const d = l.plan.pricingDetails;
224
+ return d.__typename === "AppUsagePricing" ? { id: l.id, usage: { cappedAmount: d.cappedAmount, balanceUsed: d.balanceUsed, terms: d.terms ?? "" } } : { id: l.id, recurring: { price: d.price, interval: d.interval ?? "EVERY_30_DAYS" } };
225
+ }),
226
+ });
227
+ /** The store's active subscriptions to this app (usually one), with each line's price or usage cap and balance. */
228
+ export async function activeSubscriptions(shopify) {
229
+ const data = await shopify.graphql(`query BillingActive { currentAppInstallation { activeSubscriptions { ${SUBSCRIPTION} } } }`);
230
+ return data.currentAppInstallation.activeSubscriptions.map(subscriptionOf);
231
+ }
232
+ /**
233
+ * Charges usage on a subscription's usage line: the active one's unless `lineItemId` names another. Pass an
234
+ * `idempotencyKey` (an order id, a job id) so a retried action doesn't charge twice. Shopify refuses a charge past
235
+ * the line's cap; raise it with a new subscription (`replacementBehavior: "APPLY_IMMEDIATELY"`).
236
+ */
237
+ export async function recordUsage(shopify, charge) {
238
+ let line = charge.lineItemId;
239
+ if (!line) {
240
+ line = (await activeSubscriptions(shopify)).flatMap((s) => s.lineItems).find((l) => l.usage)?.id;
241
+ if (!line)
242
+ throw new ShopifyBillingError(`${shopify.shop} has no active subscription with usage charges.`);
243
+ }
244
+ const data = await shopify.graphql(`
245
+ mutation BillingUsage($line: ID!, $price: MoneyInput!, $description: String!, $key: String) {
246
+ appUsageRecordCreate(subscriptionLineItemId: $line, price: $price, description: $description, idempotencyKey: $key) { appUsageRecord { id } userErrors { field message } }
247
+ }`, { line, price: money(charge.price), description: charge.description, key: charge.idempotencyKey ?? null });
248
+ userErrorsOf("record the usage charge", data.appUsageRecordCreate.userErrors);
249
+ return { id: data.appUsageRecordCreate.appUsageRecord.id };
250
+ }
251
+ /** Cancels a subscription; `prorate` refunds the unused part of the period. */
252
+ export async function cancelSubscription(shopify, id, o = {}) {
253
+ const data = await shopify.graphql(`
254
+ mutation BillingCancel($id: ID!, $prorate: Boolean) { appSubscriptionCancel(id: $id, prorate: $prorate) { appSubscription { id status } userErrors { field message } } }`, { id, prorate: o.prorate ?? false });
255
+ userErrorsOf("cancel the subscription", data.appSubscriptionCancel.userErrors);
256
+ return data.appSubscriptionCancel.appSubscription;
257
+ }
258
+ /**
259
+ * Shopify's plan page for an app on managed pricing (plans set in the Partner Dashboard): where to send a merchant
260
+ * to pick or change their plan. `appHandle` is the app's handle in the Partner Dashboard.
261
+ */
262
+ export function managedPricingUrl(shop, appHandle) {
263
+ return `https://admin.shopify.com/store/${shop.replace(/\.myshopify\.com$/, "")}/charges/${encodeURIComponent(appHandle)}/pricing_plans`;
264
+ }
168
265
  /**
169
266
  * The store and staff member behind a request from one of the app's pages in the Shopify admin, or null when it
170
267
  * carries no valid session token. App Bridge's `shopify.idToken()` gives the page its token; send it as
package/dist/test.d.ts CHANGED
@@ -243,8 +243,8 @@ export interface TestApp {
243
243
  export declare function createTestApp(o?: TestAppOptions): TestApp;
244
244
  /**
245
245
  * A TestApp from an app's folder (the working directory unless named): every model's schema.ib.ts, every action
246
- * file (loaded when first run, as a deployment does) and settings.ib.ts. Runs under a test runner that loads
247
- * TypeScript, like Vitest (`ib-apps test`).
246
+ * file (loaded when first run, as a deployment does) and settings.ib.ts. Runs under Vitest (`ib-apps test`), with
247
+ * this package inlined (`server.deps.inline`, as new apps' vitest.config.ts has it) so it can load TypeScript.
248
248
  */
249
249
  export declare function loadApp(dir?: string, o?: Omit<TestAppOptions, "models" | "actions" | "settings">): Promise<TestApp>;
250
250
  export {};
package/dist/test.js CHANGED
@@ -974,8 +974,8 @@ const GLOBAL_ACTION = /^api\/actions\/([^/]+)\.(ts|tsx|js|mjs)$/;
974
974
  const nodeImport = (name) => import(/* @vite-ignore */ name);
975
975
  /**
976
976
  * A TestApp from an app's folder (the working directory unless named): every model's schema.ib.ts, every action
977
- * file (loaded when first run, as a deployment does) and settings.ib.ts. Runs under a test runner that loads
978
- * TypeScript, like Vitest (`ib-apps test`).
977
+ * file (loaded when first run, as a deployment does) and settings.ib.ts. Runs under Vitest (`ib-apps test`), with
978
+ * this package inlined (`server.deps.inline`, as new apps' vitest.config.ts has it) so it can load TypeScript.
979
979
  */
980
980
  export async function loadApp(dir, o = {}) {
981
981
  const fs = await nodeImport("node:fs");
@@ -994,7 +994,18 @@ export async function loadApp(dir, o = {}) {
994
994
  };
995
995
  if (fs.existsSync(path.join(root, "api")))
996
996
  walk("api");
997
- const load = (rel) => import(/* @vite-ignore */ url.pathToFileURL(path.join(root, rel)).href);
997
+ const load = async (rel) => {
998
+ try {
999
+ return await import(/* @vite-ignore */ url.pathToFileURL(path.join(root, rel)).href);
1000
+ }
1001
+ catch (e) {
1002
+ // Node itself got the import: Vitest left this package to Node, as it does with node_modules by default.
1003
+ if (e.code === "ERR_UNKNOWN_FILE_EXTENSION") {
1004
+ throw new Error(`loadApp can't load ${rel}: Vitest has to run @inferencebureau/apps-sdk itself. Add to vitest.config.ts: test: { server: { deps: { inline: ["@inferencebureau/apps-sdk"] } } }`);
1005
+ }
1006
+ throw e;
1007
+ }
1008
+ };
998
1009
  const models = {};
999
1010
  const actions = {};
1000
1011
  for (const f of files.sort()) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "The SDK an Inference Bureau app's code imports: action helpers, metadata types, the records API client and a test harness for its actions.",
5
5
  "license": "UNLICENSED",
6
6
  "keywords": [