@inferencebureau/apps-sdk 0.8.1 → 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
@@ -180,30 +180,139 @@ export interface AppRecord {
180
180
  updatedAt: string;
181
181
  [field: string]: unknown;
182
182
  }
183
- /** Which records a list returns: `{ field: { equals: x } }`, with AND, OR and NOT lists. */
184
- export type Filter = {
185
- AND?: Filter[];
186
- OR?: Filter[];
187
- NOT?: Filter[];
188
- } & {
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 = {
189
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;
190
197
  };
191
- export type Sort = Record<string, "Ascending" | "Descending">;
192
- export interface FindManyOptions {
193
- filter?: Filter;
194
- 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"]>[];
195
202
  first?: number;
196
203
  after?: string | null;
197
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. */
198
205
  search?: string;
199
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"];
200
301
  export interface RecordPage<T = AppRecord> {
201
302
  records: T[];
202
303
  hasNextPage: boolean;
203
304
  endCursor: string | null;
204
305
  }
205
- /** A record being worked on in an action: its fields, plus what the action has asked to happen to it. */
206
- 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
+ }
207
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. */
208
317
  export declare function trackRecord<T extends object>(record: T, model?: string | null, isNew?: boolean): T;
209
318
  /** Copies the action's params onto the record: `params.<model>` when the caller nested them, else params themselves. */
@@ -291,68 +400,73 @@ export interface CheckPasswordOptions {
291
400
  email?: string;
292
401
  ip?: string;
293
402
  }
294
- export interface ModelClient {
295
- findOne(id: string): Promise<AppRecord | null>;
296
- findMany(o?: FindManyOptions): Promise<RecordPage>;
297
- 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>;
298
407
  /** Nearest records to text (embedded with the field's model) or a vector, nearest first, with `_distance`. */
299
- 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"] & {
300
409
  _distance: number;
301
410
  }>>;
302
411
  /** Writes at once. In an action, that's outside its transaction: to write with the run, `build` and `save` instead. */
303
- create(values: Record<string, unknown>): Promise<AppRecord>;
304
- 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"]>;
305
414
  delete(id: string): Promise<void>;
306
415
  /**
307
416
  * A new record for an action's `run` to `save()`, written with the action's own record in one transaction. It has
308
417
  * its id already, so other records can point at it. Only an action's `api` builds records.
309
418
  */
310
- build(values?: Record<string, unknown>): AppRecord;
419
+ build(values?: M["input"]): M["record"];
311
420
  /**
312
421
  * Whether `password` is the one stored in the record's password field (`password` unless named). Hashes are never
313
422
  * returned. Failures are counted per `email` (the record without one) and per visitor `ip`; past the limit it throws
314
423
  * an ApiError with status 429 and a message to show, without checking.
315
424
  */
316
- 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>;
317
428
  /** Runs one of the model's actions: on a record when `id` is given, else as a new one; `shop` gives it `shopify`. */
318
- run(action: string, o?: {
429
+ run<A extends keyof M["actions"] & string>(action: A, o?: {
319
430
  id?: string;
320
- params?: Record<string, unknown>;
431
+ params?: M["actions"][A]["params"];
321
432
  shop?: string;
322
433
  }): Promise<{
323
- record: AppRecord | null;
324
- result?: unknown;
434
+ record: M["record"] | null;
435
+ result?: M["actions"][A]["result"];
325
436
  }>;
326
437
  /**
327
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.
328
439
  * Give `size` and the upload takes at most that many bytes.
329
440
  */
330
- createUpload(field: string, o?: {
441
+ createUpload(field: M["files"], o?: {
331
442
  fileName?: string;
332
443
  mimeType?: string;
333
444
  size?: number;
334
445
  }): Promise<Upload>;
335
446
  /** Uploads a file for a file field, straight to storage, and answers the value to write to the field. */
336
- upload(field: string, body: Blob | ArrayBuffer | Uint8Array, o?: {
447
+ upload(field: M["files"], body: Blob | ArrayBuffer | Uint8Array, o?: {
337
448
  fileName?: string;
338
449
  mimeType?: string;
339
450
  }): Promise<{
340
451
  directUploadToken: string;
341
452
  }>;
342
453
  }
343
- export type Api = {
344
- [model: string]: ModelClient;
345
- } & {
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>>;
346
460
  /** Runs a global action (`api/actions/<name>.ts`). */
347
- $global(action: string, params?: Record<string, unknown>): Promise<{
348
- result?: unknown;
461
+ $global<A extends GlobalName>(action: A, params?: GlobalOf<A>["params"]): Promise<{
462
+ result?: GlobalOf<A>["result"];
349
463
  }>;
350
464
  /**
351
465
  * Queues an action as a background job and returns at once: a global action's name, or `<model>.<action>` (with
352
466
  * `id` for the record). It gets five minutes unless the action's `timeoutMS` says (up to 15), and is retried when
353
467
  * it fails.
354
468
  */
355
- 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>;
356
470
  /**
357
471
  * The same API for one store: store-owned models (Shopify's, and any with a text field named `shop`) show only that
358
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.
@@ -868,6 +982,25 @@ export interface ActionModule {
868
982
  onSuccess?: ActionOnSuccess;
869
983
  options?: ActionOptions;
870
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
+ }
871
1004
  export interface ShopifyPrivacyCustomer {
872
1005
  id: number;
873
1006
  email?: string | null;
@@ -895,3 +1028,4 @@ export interface ShopifyShopRedactParams {
895
1028
  shop_id: number;
896
1029
  shop_domain: string;
897
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.1",
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": [