@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 +6 -0
- package/dist/index.d.ts +167 -33
- package/dist/index.js +9 -4
- package/dist/runtime.js +2 -0
- package/dist/test.js +2 -0
- package/package.json +1 -1
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
|
-
/**
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
|
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
|
-
/**
|
|
206
|
-
|
|
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<
|
|
296
|
-
findMany(o?: FindManyOptions): Promise<RecordPage
|
|
297
|
-
findFirst(o?: Omit<FindManyOptions
|
|
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:
|
|
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:
|
|
304
|
-
update(id: string, values:
|
|
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?:
|
|
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?:
|
|
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:
|
|
429
|
+
run<A extends keyof M["actions"] & string>(action: A, o?: {
|
|
319
430
|
id?: string;
|
|
320
|
-
params?:
|
|
431
|
+
params?: M["actions"][A]["params"];
|
|
321
432
|
shop?: string;
|
|
322
433
|
}): Promise<{
|
|
323
|
-
record:
|
|
324
|
-
result?:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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:
|
|
348
|
-
result?:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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": [
|