@inferencebureau/apps-sdk 0.8.0 → 0.9.0

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
@@ -71,6 +71,12 @@ Inside an app, `createClient()` reads `IB_API_URL`, `IB_ENVIRONMENT_TOKEN`, `IB_
71
71
  Inference Bureau sets. From a script or another service, pass `{ token: process.env.IB_API_KEY, app, environment }`
72
72
  with a key linked to the app.
73
73
 
74
+ The client is typed from the app's own schemas and actions: Inference Bureau writes `web/ib-client.d.ts` whenever
75
+ one changes (`ib-apps dev` and `ib-apps pull` bring it down), and it fills in this package's `AppModels` and
76
+ `AppGlobalActions`. A misspelled model, field, filter, enum value or action then fails the type check instead of the
77
+ request. `ModelRecord<"review">` and `ModelInput<"review">` name a model's types; `api.$model(name)` reaches a model
78
+ the app may not have. Without the file the client takes any name.
79
+
74
80
  Entry points:
75
81
 
76
82
  - `@inferencebureau/apps-sdk`: metadata types, action helpers, `createClient`, `createShopifyClient`,
package/dist/index.d.ts CHANGED
@@ -47,6 +47,13 @@ export interface FieldDef {
47
47
  * webhook writes what its payload carries.
48
48
  */
49
49
  fetch?: "onWebhook" | "later";
50
+ /**
51
+ * On a synced Shopify model (products, variants, collections, customers, orders, draft orders, locations, companies,
52
+ * company locations, markets, pages, blogs, articles): the metafield the field holds, `"namespace.key"`
53
+ * (`"$app:reviews.rating"` for the app's own). Sync passes refresh it; with `fetch: "onWebhook"`, so does the
54
+ * record's webhook. A reference metafield goes in a belongsTo to the synced model it names, a list in a json field.
55
+ */
56
+ metafield?: string;
50
57
  /**
51
58
  * Computed fields, worked out when a record is read: an expression over the record's own fields (`"price * quantity"`,
52
59
  * `"concat(firstName, ' ', lastName)"`), or an aggregate over a hasMany's records. They filter and sort like stored ones.
@@ -173,30 +180,139 @@ export interface AppRecord {
173
180
  updatedAt: string;
174
181
  [field: string]: unknown;
175
182
  }
176
- /** Which records a list returns: `{ field: { equals: x } }`, with AND, OR and NOT lists. */
177
- export type Filter = {
178
- AND?: Filter[];
179
- OR?: Filter[];
180
- NOT?: Filter[];
181
- } & {
183
+ /**
184
+ * Which records a list returns: `{ field: { equals: x } }`, with AND, OR and NOT lists. `F` is a model's fields and
185
+ * their filters, from the app's generated client types (`web/ib-client.d.ts`); any field without them.
186
+ */
187
+ export type Filter<F extends object = {
182
188
  [field: string]: unknown;
189
+ }> = {
190
+ AND?: Filter<F>[];
191
+ OR?: Filter<F>[];
192
+ NOT?: Filter<F>[];
193
+ } & F;
194
+ /** A list's order: the field to sort by, or several in turn. `K` is a model's sortable fields once the client is generated. */
195
+ export type Sort<K extends string = string> = string extends K ? Record<string, SortDirection> : {
196
+ [P in K]?: SortDirection;
183
197
  };
184
- export type Sort = Record<string, "Ascending" | "Descending">;
185
- export interface FindManyOptions {
186
- filter?: Filter;
187
- sort?: Sort | Sort[];
198
+ export type SortDirection = "Ascending" | "Descending";
199
+ export interface FindManyOptions<M extends ModelTypes = UntypedModel> {
200
+ filter?: Filter<M["filter"]>;
201
+ sort?: Sort<M["sortable"]> | Sort<M["sortable"]>[];
188
202
  first?: number;
189
203
  after?: string | null;
190
204
  /** Words to find in the model's text fields: records holding every one (any case, part of a word counts), those holding the whole phrase first unless sorted. */
191
205
  search?: string;
192
206
  }
207
+ /** A field's filter: `null` matches records without a value (or holding the field's default when that's null). */
208
+ export interface FieldFilter<V> {
209
+ equals?: V | null;
210
+ notEquals?: V | null;
211
+ in?: (V | null)[];
212
+ notIn?: (V | null)[];
213
+ isSet?: boolean;
214
+ }
215
+ /** Numbers, dates and text compare by value. */
216
+ export interface OrderedFilter<V> extends FieldFilter<V> {
217
+ lessThan?: V;
218
+ lessThanOrEqual?: V;
219
+ greaterThan?: V;
220
+ greaterThanOrEqual?: V;
221
+ }
222
+ /** `startsWith` matches case and all; `contains` ignores case. */
223
+ export interface StringFilter<V extends string = string> extends OrderedFilter<V> {
224
+ startsWith?: string;
225
+ contains?: string;
226
+ }
227
+ /** Dates as ISO 8601 text or a Date. */
228
+ export type DateTimeFilter = OrderedFilter<string | Date>;
229
+ /**
230
+ * The app's models, filled in by `web/ib-client.d.ts`: Inference Bureau writes that file into development whenever a
231
+ * schema or an action changes, `ib-apps dev` and `ib-apps pull` bring it down, and deploys carry it to production.
232
+ * With it, `createClient()`, an action's `api` and a session's `api` know every model, field and action, so a typo
233
+ * fails the type check instead of the request. Without it (an app that has none yet), the API takes any name.
234
+ */
235
+ export interface AppModels {
236
+ }
237
+ /** The app's global actions (`api/actions/*.ts`), filled in by `web/ib-client.d.ts` like `AppModels`. */
238
+ export interface AppGlobalActions {
239
+ }
240
+ /** What the generated file says of one model. */
241
+ export interface ModelTypes {
242
+ /** A record as reads return it. */
243
+ record: AppRecord;
244
+ /** What `create`, `update` and `build` take: every field optional, the API checks validations. */
245
+ input: Record<string, unknown>;
246
+ /** Each field the model can filter on, with its filter. */
247
+ filter: object;
248
+ /** The fields it can sort on. */
249
+ sortable: string;
250
+ /** Its vector fields (`search`), file fields (`createUpload`, `upload`) and password fields (`checkPassword`). */
251
+ vectors: string;
252
+ files: string;
253
+ passwords: string;
254
+ /** Its actions (api/models/<model>/actions/*.ts). */
255
+ actions: {
256
+ [action: string]: ActionTypes;
257
+ };
258
+ }
259
+ /** An action's `params` and what it returns: `unknown` when its options say `returnType: true`, else nothing. */
260
+ export interface ActionTypes {
261
+ params: Record<string, unknown>;
262
+ result: unknown;
263
+ }
264
+ /** A model as the API sees it without generated types: any field, any action. */
265
+ export interface UntypedModel {
266
+ record: AppRecord;
267
+ input: Record<string, unknown>;
268
+ filter: {
269
+ [field: string]: unknown;
270
+ };
271
+ sortable: string;
272
+ vectors: string;
273
+ files: string;
274
+ passwords: string;
275
+ actions: {
276
+ [action: string]: ActionTypes;
277
+ };
278
+ }
279
+ type Typed<T> = keyof T extends never ? false : true;
280
+ /** The model clients: the generated file's models, or any name before there is one. */
281
+ export type ModelClients = Typed<AppModels> extends true ? {
282
+ [K in keyof AppModels]: ModelClient<AppModels[K] extends ModelTypes ? AppModels[K] : UntypedModel>;
283
+ } : {
284
+ [model: string]: ModelClient;
285
+ };
286
+ type Globals = Typed<AppGlobalActions> extends true ? AppGlobalActions : {
287
+ [action: string]: ActionTypes;
288
+ };
289
+ type GlobalName = keyof Globals & string;
290
+ type GlobalOf<A extends string> = A extends keyof Globals ? (Globals[A] extends ActionTypes ? Globals[A] : ActionTypes) : ActionTypes;
291
+ /** What `enqueue` takes: a global action, or `<model>.<action>`. */
292
+ export type ActionName = Typed<AppModels> extends true ? GlobalName | {
293
+ [K in keyof AppModels & string]: AppModels[K] extends ModelTypes ? `${K}.${keyof AppModels[K]["actions"] & string}` : never;
294
+ }[keyof AppModels & string] : string;
295
+ type ModelOf<N extends string> = N extends keyof AppModels ? (AppModels[N] extends ModelTypes ? AppModels[N] : UntypedModel) : UntypedModel;
296
+ /** A model's record as the API reads it, by name: `ModelRecord<"review">`. Any record before the app has generated types. */
297
+ export type ModelRecord<N extends string> = ModelOf<N>["record"];
298
+ /** What creating or updating a model's record takes, by name. */
299
+ export type ModelInput<N extends string> = ModelOf<N>["input"];
300
+ type ParamsOf<A extends string> = A extends `${infer M}.${infer N}` ? M extends keyof AppModels ? AppModels[M] extends ModelTypes ? N extends keyof AppModels[M]["actions"] ? AppModels[M]["actions"][N]["params"] : never : never : GlobalOf<A>["params"] : GlobalOf<A>["params"];
193
301
  export interface RecordPage<T = AppRecord> {
194
302
  records: T[];
195
303
  hasNextPage: boolean;
196
304
  endCursor: string | null;
197
305
  }
198
- /** A record being worked on in an action: its fields, plus what the action has asked to happen to it. */
199
- export type ActionRecord = AppRecord;
306
+ /**
307
+ * A record being worked on in an action: its fields, plus what the action has asked to happen to it. Its fields read
308
+ * as `any`, since one action file doesn't say which model's it is, so they pass to the generated client's typed calls.
309
+ */
310
+ export interface ActionRecord {
311
+ id: string;
312
+ createdAt: string;
313
+ updatedAt: string;
314
+ [field: string]: any;
315
+ }
200
316
  /** Marks a plain object as a record `save` can write: the action's own (the runtime does this before `run`), or one its `api` read or built. */
201
317
  export declare function trackRecord<T extends object>(record: T, model?: string | null, isNew?: boolean): T;
202
318
  /** Copies the action's params onto the record: `params.<model>` when the caller nested them, else params themselves. */
@@ -284,68 +400,73 @@ export interface CheckPasswordOptions {
284
400
  email?: string;
285
401
  ip?: string;
286
402
  }
287
- export interface ModelClient {
288
- findOne(id: string): Promise<AppRecord | null>;
289
- findMany(o?: FindManyOptions): Promise<RecordPage>;
290
- findFirst(o?: Omit<FindManyOptions, "first" | "after">): Promise<AppRecord | null>;
403
+ export interface ModelClient<M extends ModelTypes = UntypedModel> {
404
+ findOne(id: string): Promise<M["record"] | null>;
405
+ findMany(o?: FindManyOptions<M>): Promise<RecordPage<M["record"]>>;
406
+ findFirst(o?: Omit<FindManyOptions<M>, "first" | "after">): Promise<M["record"] | null>;
291
407
  /** Nearest records to text (embedded with the field's model) or a vector, nearest first, with `_distance`. */
292
- search(field: string, near: string | number[], o?: Omit<FindManyOptions, "sort" | "search">): Promise<RecordPage<AppRecord & {
408
+ search(field: M["vectors"], near: string | number[], o?: Omit<FindManyOptions<M>, "sort" | "search">): Promise<RecordPage<M["record"] & {
293
409
  _distance: number;
294
410
  }>>;
295
411
  /** Writes at once. In an action, that's outside its transaction: to write with the run, `build` and `save` instead. */
296
- create(values: Record<string, unknown>): Promise<AppRecord>;
297
- update(id: string, values: Record<string, unknown>): Promise<AppRecord>;
412
+ create(values: M["input"]): Promise<M["record"]>;
413
+ update(id: string, values: M["input"]): Promise<M["record"]>;
298
414
  delete(id: string): Promise<void>;
299
415
  /**
300
416
  * A new record for an action's `run` to `save()`, written with the action's own record in one transaction. It has
301
417
  * its id already, so other records can point at it. Only an action's `api` builds records.
302
418
  */
303
- build(values?: Record<string, unknown>): AppRecord;
419
+ build(values?: M["input"]): M["record"];
304
420
  /**
305
421
  * Whether `password` is the one stored in the record's password field (`password` unless named). Hashes are never
306
422
  * returned. Failures are counted per `email` (the record without one) and per visitor `ip`; past the limit it throws
307
423
  * an ApiError with status 429 and a message to show, without checking.
308
424
  */
309
- checkPassword(id: string, password: string, field?: string | CheckPasswordOptions): Promise<boolean>;
425
+ checkPassword(id: string, password: string, field?: M["passwords"] | (CheckPasswordOptions & {
426
+ field?: M["passwords"];
427
+ })): Promise<boolean>;
310
428
  /** Runs one of the model's actions: on a record when `id` is given, else as a new one; `shop` gives it `shopify`. */
311
- run(action: string, o?: {
429
+ run<A extends keyof M["actions"] & string>(action: A, o?: {
312
430
  id?: string;
313
- params?: Record<string, unknown>;
431
+ params?: M["actions"][A]["params"];
314
432
  shop?: string;
315
433
  }): Promise<{
316
- record: AppRecord | null;
317
- result?: unknown;
434
+ record: M["record"] | null;
435
+ result?: M["actions"][A]["result"];
318
436
  }>;
319
437
  /**
320
438
  * A direct upload for a file field, for a browser to PUT a file to (up to 1 GiB) without it passing through the app.
321
439
  * Give `size` and the upload takes at most that many bytes.
322
440
  */
323
- createUpload(field: string, o?: {
441
+ createUpload(field: M["files"], o?: {
324
442
  fileName?: string;
325
443
  mimeType?: string;
326
444
  size?: number;
327
445
  }): Promise<Upload>;
328
446
  /** Uploads a file for a file field, straight to storage, and answers the value to write to the field. */
329
- upload(field: string, body: Blob | ArrayBuffer | Uint8Array, o?: {
447
+ upload(field: M["files"], body: Blob | ArrayBuffer | Uint8Array, o?: {
330
448
  fileName?: string;
331
449
  mimeType?: string;
332
450
  }): Promise<{
333
451
  directUploadToken: string;
334
452
  }>;
335
453
  }
336
- export type Api = {
337
- [model: string]: ModelClient;
338
- } & {
454
+ export type Api = ModelClients & {
455
+ /**
456
+ * A model by name, for one the app may not have: a Shopify model it syncs only once it's chosen. Typed as
457
+ * `api.<model>` is when the generated types list it, any name otherwise; a model that doesn't exist answers 404.
458
+ */
459
+ $model<N extends string>(name: N): ModelClient<ModelOf<N>>;
339
460
  /** Runs a global action (`api/actions/<name>.ts`). */
340
- $global(action: string, params?: Record<string, unknown>): Promise<{
341
- result?: unknown;
461
+ $global<A extends GlobalName>(action: A, params?: GlobalOf<A>["params"]): Promise<{
462
+ result?: GlobalOf<A>["result"];
342
463
  }>;
343
464
  /**
344
465
  * Queues an action as a background job and returns at once: a global action's name, or `<model>.<action>` (with
345
466
  * `id` for the record). It gets five minutes unless the action's `timeoutMS` says (up to 15), and is retried when
346
467
  * it fails.
347
468
  */
348
- enqueue(action: string, params?: Record<string, unknown>, options?: EnqueueOptions): Promise<Job>;
469
+ enqueue<A extends ActionName>(action: A, params?: ParamsOf<A>, options?: EnqueueOptions): Promise<Job>;
349
470
  /**
350
471
  * The same API for one store: store-owned models (Shopify's, and any with a text field named `shop`) show only that
351
472
  * store's records, new ones are made as its, and actions run for it. An action's `api` is already its run's store's.
@@ -861,6 +982,25 @@ export interface ActionModule {
861
982
  onSuccess?: ActionOnSuccess;
862
983
  options?: ActionOptions;
863
984
  }
985
+ /**
986
+ * `export const params` in an action file: what callers pass it, for the app's generated client types
987
+ * (`web/ib-client.d.ts`) to check calls by. Keep it a plain object literal: Inference Bureau reads it from the file.
988
+ * It isn't checked at run time. A create or update action takes the model's fields as well.
989
+ *
990
+ * export const params: ActionParams = { note: { type: "string" }, notify: { type: "boolean", required: true } };
991
+ */
992
+ export type ActionParams = Record<string, ParamDef>;
993
+ export interface ParamDef {
994
+ type: "string" | "number" | "boolean" | "dateTime" | "enum" | "json" | "object" | "array";
995
+ /** Callers must pass it. */
996
+ required?: boolean;
997
+ /** enum: the values it takes. */
998
+ options?: string[];
999
+ /** object: its keys. */
1000
+ properties?: Record<string, ParamDef>;
1001
+ /** array: each item. */
1002
+ items?: ParamDef;
1003
+ }
864
1004
  export interface ShopifyPrivacyCustomer {
865
1005
  id: number;
866
1006
  email?: string | null;
@@ -888,3 +1028,4 @@ export interface ShopifyShopRedactParams {
888
1028
  shop_id: number;
889
1029
  shop_domain: string;
890
1030
  }
1031
+ export {};
package/dist/index.js CHANGED
@@ -171,6 +171,8 @@ export function createClient(o = {}) {
171
171
  };
172
172
  };
173
173
  const cache = new Map();
174
+ const modelNamed = (name) => { if (!cache.has(name))
175
+ cache.set(name, model(name)); return cache.get(name); };
174
176
  const $global = (action, params = {}) => call("POST", `/actions/${encodeURIComponent(action)}`, { params });
175
177
  const enqueue = (action, params = {}, o = {}) => call("POST", "/jobs", { action, params, ...o, ...(o.runAt instanceof Date ? { runAt: o.runAt.toISOString() } : {}) });
176
178
  const sync = "/shopify/sync";
@@ -206,6 +208,8 @@ export function createClient(o = {}) {
206
208
  get(_t, prop) {
207
209
  if (prop === "$global")
208
210
  return $global;
211
+ if (prop === "$model")
212
+ return modelNamed;
209
213
  if (prop === "enqueue")
210
214
  return enqueue;
211
215
  if (prop === "forShop")
@@ -216,9 +220,7 @@ export function createClient(o = {}) {
216
220
  return shopifySync;
217
221
  if (typeof prop !== "string" || prop === "then")
218
222
  return undefined;
219
- if (!cache.has(prop))
220
- cache.set(prop, model(prop));
221
- return cache.get(prop);
223
+ return modelNamed(prop);
222
224
  },
223
225
  });
224
226
  }
@@ -387,7 +389,10 @@ export async function currentPlan(shopify, o = {}) {
387
389
  let read = false;
388
390
  if (o.api) {
389
391
  try {
390
- const r = await o.api.shopifyAppSubscription.findFirst({ filter: { shop: { equals: shopify.shop }, status: { equals: "active" } }, sort: { shopifyCreatedAt: "Descending" } });
392
+ // By name: an app that doesn't sync it has no such model in its generated types. An api made by an older copy of
393
+ // the SDK has no $model.
394
+ const subs = typeof o.api.$model === "function" ? o.api.$model("shopifyAppSubscription") : o.api.shopifyAppSubscription;
395
+ const r = await subs.findFirst({ filter: { shop: { equals: shopify.shop }, status: { equals: "active" } }, sort: { shopifyCreatedAt: "Descending" } });
391
396
  read = true;
392
397
  if (r)
393
398
  sub = { name: String(r.name ?? ""), status: "ACTIVE", subscriptionId: String(r.shopifyId), test: r.test === true, currentPeriodEnd: r.currentPeriodEnd ?? null, trialDays: Number(r.trialDays ?? 0), createdAt: String(r.shopifyCreatedAt ?? r.createdAt), source: "synced" };
package/dist/runtime.js CHANGED
@@ -61,6 +61,8 @@ function stagingApi(api, handed) {
61
61
  const v = Reflect.get(target, prop, receiver);
62
62
  if (prop === "forShop" || prop === "asRole")
63
63
  return (...args) => stagingApi(v.apply(target, args), handed);
64
+ if (prop === "$model")
65
+ return (name) => receiver[name];
64
66
  if (typeof prop !== "string" || prop.startsWith("$") || prop === "then" || prop === "enqueue" || prop === "shopifySync" || !v || typeof v !== "object")
65
67
  return v;
66
68
  if (!models.has(prop))
package/dist/test.js CHANGED
@@ -1977,6 +1977,8 @@ export function createTestApp(o = {}) {
1977
1977
  get(_t, prop) {
1978
1978
  if (prop === "$global")
1979
1979
  return $global;
1980
+ if (prop === "$model")
1981
+ return (name) => made[name];
1980
1982
  if (prop === "enqueue")
1981
1983
  return queue;
1982
1984
  if (prop === "forShop")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
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": [