@inferencebureau/apps-sdk 0.14.0 → 0.15.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/dist/index.d.ts CHANGED
@@ -246,11 +246,80 @@ export interface FindManyOptions<M extends ModelTypes = UntypedModel, S extends
246
246
  * library that asks for an offset; at most 10,000, and not with `after`. Cursors are faster for reading every page.
247
247
  */
248
248
  skip?: number;
249
- /** 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. */
249
+ /** Words to find in the model's text fields: records holding every one (any case, part of a word counts), the best matches first unless sorted: the words together, words that start or are whole words, short fields over rich text. */
250
250
  search?: string;
251
251
  /** Which fields to read, and which related records with them (SelectOf); every field and no related records when left out. */
252
252
  select?: S;
253
253
  }
254
+ /**
255
+ * An aggregate: `{ count: true }` counts records, `{ count: "field" }` those holding a value in it, and `{ sum | avg |
256
+ * min | max: "field" }` works one out over a number field (min and max also over dates and text).
257
+ */
258
+ export type AggregateSpec<F extends string = string> = {
259
+ count: true | F;
260
+ } | {
261
+ sum: F;
262
+ } | {
263
+ avg: F;
264
+ } | {
265
+ min: F;
266
+ } | {
267
+ max: F;
268
+ };
269
+ export type DateInterval = "hour" | "day" | "week" | "month" | "quarter" | "year";
270
+ /**
271
+ * An aggregate query (`aggregate`): the aggregates to work out, each by the name it answers with, over the records
272
+ * `filter` and `search` leave, in groups by `groupBy`'s fields or one group of them all. A dateTime groups by
273
+ * `{ field, interval }` into buckets in `timeZone` (UTC unless given), labelled "2026-10-21T14:00" (hour),
274
+ * "2026-10-21" (day, and week from its Monday), "2026-10", "2026-Q4" or "2026". `sort` orders the groups by a field
275
+ * they're grouped by or an aggregate's name; by the groups' values otherwise. `first` groups (100 unless given, at
276
+ * most 1000), and `hasMore` says when there are more.
277
+ *
278
+ * const { groups } = await api.review.aggregate({
279
+ * groupBy: ["product", { field: "createdAt", interval: "month" }],
280
+ * aggregates: { reviews: { count: true }, rating: { avg: "rating" } },
281
+ * filter: { status: { equals: "approved" } },
282
+ * });
283
+ * // [{ product: "rec_…", createdAt: "2026-10", reviews: 12, rating: 4.25 }, …]
284
+ */
285
+ export interface AggregateOptions<M extends ModelTypes = UntypedModel, A extends {
286
+ [name: string]: AggregateSpec<M["sortable"]>;
287
+ } = {
288
+ [name: string]: AggregateSpec<M["sortable"]>;
289
+ }> {
290
+ groupBy?: (M["sortable"] | {
291
+ field: M["sortable"];
292
+ interval: DateInterval;
293
+ })[];
294
+ aggregates: A;
295
+ filter?: Filter<M["filter"]>;
296
+ search?: string;
297
+ sort?: {
298
+ [name: string]: SortDirection;
299
+ } | {
300
+ [name: string]: SortDirection;
301
+ }[];
302
+ first?: number;
303
+ timeZone?: string;
304
+ }
305
+ /** One group: the values it's grouped by, and each aggregate by its name (a count is always a number). */
306
+ export type AggregateGroup<A = {
307
+ [name: string]: AggregateSpec;
308
+ }> = string extends keyof A ? {
309
+ [field: string]: string | number | boolean | null;
310
+ } : {
311
+ [K in keyof A]: A[K] extends {
312
+ count: unknown;
313
+ } ? number : number | string | null;
314
+ } & {
315
+ [field: string]: string | number | boolean | null;
316
+ };
317
+ export interface AggregateResult<A = {
318
+ [name: string]: AggregateSpec;
319
+ }> {
320
+ groups: AggregateGroup<A>[];
321
+ hasMore: boolean;
322
+ }
254
323
  /**
255
324
  * What a read's `select` names: fields as `true` (the id always comes), and relationships as `true` for their records
256
325
  * with every field, or `{ select }` to choose theirs. A hasMany or hasManyThrough also takes `filter`, `sort` and
@@ -599,6 +668,10 @@ export interface ModelClient<M extends ModelTypes = UntypedModel> {
599
668
  }): Promise<ReadOf<M, S> | null>;
600
669
  findMany<S extends SelectOf<M> | undefined = undefined>(o?: FindManyOptions<M, S>): Promise<RecordPage<ReadOf<M, S>>>;
601
670
  findFirst<S extends SelectOf<M> | undefined = undefined>(o?: Omit<FindManyOptions<M, S>, "first" | "after">): Promise<ReadOf<M, S> | null>;
671
+ /** Counts, sums, averages, least and most over the records, in groups or all together (AggregateOptions). */
672
+ aggregate<A extends {
673
+ [name: string]: AggregateSpec<M["sortable"]>;
674
+ }>(o: AggregateOptions<M, A>): Promise<AggregateResult<A>>;
602
675
  /** Nearest records to text (embedded with the field's model) or a vector, nearest first, with `_distance`. */
603
676
  search<S extends SelectOf<M> | undefined = undefined>(field: M["vectors"], near: string | number[], o?: Omit<FindManyOptions<M, S>, "sort" | "search">): Promise<RecordPage<ReadOf<M, S> & {
604
677
  _distance: number;
@@ -678,6 +751,12 @@ export type Api = ModelClients & {
678
751
  * `api.<model>` is when the generated types list it, any name otherwise; a model that doesn't exist answers 404.
679
752
  */
680
753
  $model<N extends string>(name: N): ModelClient<ModelOf<N>>;
754
+ /**
755
+ * Which of the models had records created, updated or deleted since `cursor`, for a live query to read again.
756
+ * Waits up to `wait` seconds (25 at most) for one to; without a cursor it answers at once with one to start from.
757
+ * Held to the client's store and role as reads are: a store's client hears only of its records.
758
+ */
759
+ $changes(o: ChangesOptions): Promise<Changes>;
681
760
  /** Runs a global action (`api/actions/<name>.ts`). */
682
761
  $global<A extends GlobalName>(action: A, params?: GlobalOf<A>["params"]): Promise<{
683
762
  result?: GlobalOf<A>["result"];
@@ -710,7 +789,60 @@ export type Api = ModelClients & {
710
789
  asRole(role: string, session?: CallerSession): Api;
711
790
  /** Shopify sync on demand: one store, some or all of its synced models, everything or what changed since a date. */
712
791
  shopifySync: ShopifySync;
792
+ /**
793
+ * The app's own files, by path, apart from any record: an export, a generated image, an asset an action makes.
794
+ * Under `public/` a file is on the CDN with a lasting URL; anywhere else it's private, read through a URL signed for
795
+ * an hour. Counted in the app's storage. Not through a role-held `api`: hand a browser a file's URL from a route.
796
+ */
797
+ files: FilesClient;
713
798
  };
799
+ /** A file in the app's storage. `url` is the CDN's for a public file and signed for an hour for a private one. */
800
+ export interface StorageFile {
801
+ path: string;
802
+ access: "private" | "public";
803
+ url: string | null;
804
+ size: number;
805
+ mimeType: string | null;
806
+ uploadedAt: string;
807
+ }
808
+ export interface StoragePage {
809
+ files: StorageFile[];
810
+ hasNextPage: boolean;
811
+ endCursor: string | null;
812
+ }
813
+ /** A direct upload to storage: PUT the file to `url` with `headers` within the hour; it lands at its path. */
814
+ export interface StorageUpload {
815
+ url: string;
816
+ method: "PUT";
817
+ headers: Record<string, string>;
818
+ expiresAt: string;
819
+ }
820
+ /** The most bytes `files.put` sends in the request itself; a bigger file goes straight to storage. */
821
+ export declare const STORAGE_INLINE_BYTES: number;
822
+ export interface FilesClient {
823
+ /**
824
+ * Stores a file at `path` (segments of letters, digits, `.`, `_` and `-`), replacing one there, up to 1 GiB: over
825
+ * 4 MiB it goes straight to storage. The type is `mimeType`, else the Blob's, else guessed from the path.
826
+ */
827
+ put(path: string, body: Blob | ArrayBuffer | Uint8Array | string, o?: {
828
+ mimeType?: string;
829
+ }): Promise<StorageFile>;
830
+ /** The file at `path`, with a fresh `url`, or null. */
831
+ get(path: string): Promise<StorageFile | null>;
832
+ /** The files under `prefix` (all of them without one), private ones first: a page of `first` (100 unless given, up to 1000), `after` the previous page's `endCursor`. */
833
+ list(o?: {
834
+ prefix?: string;
835
+ first?: number;
836
+ after?: string | null;
837
+ }): Promise<StoragePage>;
838
+ /** Deletes the file at `path`; nothing happens when there's none. */
839
+ delete(path: string): Promise<void>;
840
+ /** A direct upload for a browser to PUT to (or any file over 4 MiB): at most `size` bytes when given, of `mimeType` (else guessed from the path). */
841
+ createUpload(path: string, o?: {
842
+ mimeType?: string;
843
+ size?: number;
844
+ }): Promise<StorageUpload>;
845
+ }
714
846
  export interface SyncRunOptions {
715
847
  /** The store (x.myshopify.com); an `api.forShop(shop)` client's own store when left out. */
716
848
  shop?: string;
@@ -767,6 +899,19 @@ export interface ShopifySync {
767
899
  /** Stops a running run before its next page; what it wrote stays. */
768
900
  abort(id: string): Promise<SyncRun>;
769
901
  }
902
+ export interface ChangesOptions {
903
+ /** The models to hear about, by name. */
904
+ models: string[];
905
+ /** From the last answer; without one the answer is a cursor for now. */
906
+ cursor?: string | null;
907
+ /** Seconds to wait for a change before answering that none came (0 to 25). */
908
+ wait?: number;
909
+ }
910
+ /** What changed since a cursor: the models, by name, and the cursor to ask with next. */
911
+ export interface Changes {
912
+ cursor: string;
913
+ models: string[];
914
+ }
770
915
  /** Who a role-scoped call is for, filling `{ $session: … }` in permissions.ib.ts filters. */
771
916
  export interface CallerSession {
772
917
  userId?: string | null;
@@ -831,6 +976,10 @@ export type RecordsRequest = {
831
976
  model: string;
832
977
  id: string;
833
978
  select?: Record<string, unknown>;
979
+ } | {
980
+ op: "aggregate";
981
+ model: string;
982
+ options: AggregateOptions;
834
983
  } | {
835
984
  op: "create";
836
985
  model: string;
@@ -865,12 +1014,21 @@ export type RecordsRequest = {
865
1014
  op: "global";
866
1015
  action: string;
867
1016
  params?: Record<string, unknown>;
1017
+ } | {
1018
+ op: "changes";
1019
+ models: string[];
1020
+ cursor?: string | null;
868
1021
  };
869
1022
  export interface ServeRecordsOptions {
870
1023
  /** The models the route answers for; every model when unset. */
871
1024
  models?: string[];
872
1025
  /** The global actions it runs; none when unset. */
873
1026
  globalActions?: string[];
1027
+ /**
1028
+ * Seconds a live query's watch waits for a change before the route answers that none came (25 unless given, 0 to
1029
+ * 25). The route's function must be allowed to run that long; a shorter wait just means more requests.
1030
+ */
1031
+ liveWait?: number;
874
1032
  }
875
1033
  /**
876
1034
  * The app's records route, for its pages' own scripts: the hooks and AutoTable/AutoForm in
package/dist/index.js CHANGED
@@ -129,6 +129,8 @@ export class ApiError extends Error {
129
129
  }
130
130
  /** The most records one bulk call takes. */
131
131
  export const MAX_BULK = 250;
132
+ /** The most bytes `files.put` sends in the request itself; a bigger file goes straight to storage. */
133
+ export const STORAGE_INLINE_BYTES = 4 * 1024 * 1024;
132
134
  const envVar = (name) => globalThis.process?.env?.[name];
133
135
  /** The app's API. In an app's deployment every option comes from its environment variables. */
134
136
  export function createClient(o = {}) {
@@ -143,10 +145,11 @@ export function createClient(o = {}) {
143
145
  ...(o.shop ? { "x-ib-shop": o.shop } : {}), ...(o.role ? { "x-ib-role": o.role } : {}),
144
146
  ...(o.role && o.session ? { "x-ib-session": JSON.stringify({ userId: o.session.userId ?? null, customerId: o.session.customerId ?? null, ...(o.session.customerRecordId ? { customerRecordId: o.session.customerRecordId } : {}) }) } : {}),
145
147
  };
146
- async function call(method, path, body) {
148
+ /** A call with a JSON body (or none); `raw` sends bytes as they are, with their type when known. */
149
+ async function call(method, path, body, raw) {
147
150
  const res = await f(`${base}${path}`, {
148
- method, headers: { authorization: `Bearer ${token}`, ...scope, ...(body === undefined ? {} : { "content-type": "application/json" }) },
149
- ...(body === undefined ? {} : { body: JSON.stringify(body) }),
151
+ method, headers: { authorization: `Bearer ${token}`, ...scope, ...(raw ? (raw.type ? { "content-type": raw.type } : {}) : body === undefined ? {} : { "content-type": "application/json" }) },
152
+ ...(raw ? { body: raw.body } : body === undefined ? {} : { body: JSON.stringify(body) }),
150
153
  });
151
154
  if (res.status === 204)
152
155
  return undefined;
@@ -181,6 +184,7 @@ export function createClient(o = {}) {
181
184
  findMany: (o = {}) => query({ ...o }),
182
185
  findFirst: async (o = {}) => (await query({ ...o, first: 1 })).records[0] ?? null,
183
186
  search: (field, near, o = {}) => query({ ...o, search: { field, near } }),
187
+ aggregate: (o) => call("POST", `${m}/records/aggregate`, o),
184
188
  create: (values) => call("POST", `${m}/records`, values),
185
189
  update: (id, values) => call("PATCH", `${m}/records/${encodeURIComponent(id)}`, values),
186
190
  delete: (id) => call("DELETE", `${m}/records/${encodeURIComponent(id)}`),
@@ -212,6 +216,7 @@ export function createClient(o = {}) {
212
216
  const modelNamed = (name) => { if (!cache.has(name))
213
217
  cache.set(name, model(name)); return cache.get(name); };
214
218
  const $global = (action, params = {}) => call("POST", `/actions/${encodeURIComponent(action)}`, { params });
219
+ const $changes = (q) => call("POST", "/changes", { models: q.models, ...(q.cursor ? { cursor: q.cursor } : {}), ...(q.wait !== undefined ? { wait: q.wait } : {}) });
215
220
  const enqueue = (action, params = {}, o = {}) => call("POST", "/jobs", { action, params, ...o, ...(o.runAt instanceof Date ? { runAt: o.runAt.toISOString() } : {}) });
216
221
  const enqueueMany = async (action, jobs, o = {}) => (await call("POST", "/jobs/bulk", { action, jobs, ...o, ...(o.runAt instanceof Date ? { runAt: o.runAt.toISOString() } : {}) })).jobs;
217
222
  const sync = "/shopify/sync";
@@ -241,12 +246,41 @@ export function createClient(o = {}) {
241
246
  list: async (q = {}) => (await call("GET", `${sync}?${new URLSearchParams({ ...(q.shop ? { shop: q.shop } : {}), ...(q.limit ? { limit: String(q.limit) } : {}) })}`)).data,
242
247
  abort: (id) => call("POST", `${sync}/${encodeURIComponent(id)}/abort`),
243
248
  };
249
+ const storagePath = (path) => `/storage/${path.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/")}`;
250
+ const files = {
251
+ async put(path, body, q = {}) {
252
+ const blob = body instanceof Blob ? body : new Blob([body]);
253
+ const mimeType = q.mimeType ?? (blob.type || undefined);
254
+ if (blob.size <= STORAGE_INLINE_BYTES)
255
+ return call("PUT", storagePath(path), undefined, { body: blob, type: mimeType });
256
+ const up = await call("POST", "/storage/uploads", { path, size: blob.size, ...(mimeType ? { mimeType } : {}) });
257
+ const res = await f(up.url, { method: "PUT", headers: up.headers, body: blob });
258
+ if (!res.ok)
259
+ throw new ApiError(`The upload was refused (${res.status}): ${(await res.text()).slice(0, 300)}`, res.status, "upload_failed");
260
+ return call("GET", storagePath(path));
261
+ },
262
+ async get(path) {
263
+ try {
264
+ return await call("GET", storagePath(path));
265
+ }
266
+ catch (e) {
267
+ if (e instanceof ApiError && e.status === 404)
268
+ return null;
269
+ throw e;
270
+ }
271
+ },
272
+ list: (q = {}) => call("GET", `/storage?${new URLSearchParams({ ...(q.prefix ? { prefix: q.prefix } : {}), ...(q.first ? { first: String(q.first) } : {}), ...(q.after ? { after: q.after } : {}) })}`),
273
+ delete: (path) => call("DELETE", storagePath(path)),
274
+ createUpload: (path, q = {}) => call("POST", "/storage/uploads", { path, ...q }),
275
+ };
244
276
  const forShop = (shop) => createClient({ ...o, url, token, app, environment, fetch: f, shop });
245
277
  const asRole = (role, session) => createClient({ ...o, url, token, app, environment, fetch: f, role, ...(session ? { session } : {}) });
246
278
  return new Proxy({}, {
247
279
  get(_t, prop) {
248
280
  if (prop === "$global")
249
281
  return $global;
282
+ if (prop === "$changes")
283
+ return $changes;
250
284
  if (prop === "$model")
251
285
  return modelNamed;
252
286
  if (prop === "enqueue")
@@ -259,6 +293,8 @@ export function createClient(o = {}) {
259
293
  return asRole;
260
294
  if (prop === "shopifySync")
261
295
  return shopifySync;
296
+ if (prop === "files")
297
+ return files;
262
298
  if (typeof prop !== "string" || prop === "then")
263
299
  return undefined;
264
300
  return modelNamed(prop);
@@ -300,6 +336,17 @@ export async function serveRecords(request, api, o = {}) {
300
336
  return errorBody(403, "forbidden", `This route doesn't run ${String(body.action)}.`);
301
337
  return Response.json(await api.$global(body.action, obj(body.params)));
302
338
  }
339
+ // A live query's watch: which of its models changed, waiting for one to (#125).
340
+ if (body.op === "changes") {
341
+ const names = Array.isArray(body.models) ? body.models : [];
342
+ if (!names.length || !names.every(str))
343
+ return errorBody(400, "invalid_request", "Name the models to watch.");
344
+ const other = o.models ? names.find((n) => !o.models.includes(n)) : undefined;
345
+ if (other)
346
+ return errorBody(403, "forbidden", `This route doesn't answer for ${other}.`);
347
+ const wait = Math.min(Math.max(o.liveWait ?? 25, 0), 25);
348
+ return Response.json(await api.$changes({ models: names, cursor: str(body.cursor) ? body.cursor : null, wait }));
349
+ }
303
350
  if (!str(body.model))
304
351
  return errorBody(400, "invalid_request", "The body names no model.");
305
352
  if (o.models && !o.models.includes(body.model))
@@ -309,6 +356,7 @@ export async function serveRecords(request, api, o = {}) {
309
356
  switch (body.op) {
310
357
  case "describe": return Response.json(await m.describe());
311
358
  case "findMany": return Response.json(await m.findMany(obj(b.options)));
359
+ case "aggregate": return Response.json(await m.aggregate(obj(b.options)));
312
360
  case "findOne": {
313
361
  if (!str(b.id))
314
362
  break;
package/dist/react.d.ts CHANGED
@@ -8,9 +8,14 @@
8
8
  * globals.css) and their CSS variables, so they look like the rest of the app. `@inferencebureau/apps-sdk/polaris`
9
9
  * draws the same tables and forms in Polaris web components. Both draw what `useAutoTable` and `useAutoForm` work out,
10
10
  * which a page can use to draw its own.
11
+ *
12
+ * A read given `live: true` reads again whenever its model's records change, whoever changes them: an action, a
13
+ * Shopify sync, another tab. The client keeps one watch open on the records route for every live read on the page
14
+ * (a long poll, paused while the tab is hidden), and the route answers which models changed; the read that follows
15
+ * goes through the route like any other, so it sees only what the viewer may.
11
16
  */
12
17
  import { type FormEvent, type ReactNode } from "react";
13
- import { ApiError, type AppRecord, type BulkDeleteResult, type Filter, type FindManyOptions, type ModelDescription, type RecordPage, type Sort } from "./index.js";
18
+ import { ApiError, type AggregateOptions, type AggregateResult, type AppRecord, type BulkDeleteResult, type Filter, type FindManyOptions, type ModelDescription, type RecordPage, type Sort } from "./index.js";
14
19
  import { type Column, type ColumnOption, type Display, type FieldOption, type FormFieldSpec, type FormValue, type SortOption } from "./auto.js";
15
20
  export { labelOf, recordLabel } from "./auto.js";
16
21
  export type { Column, ColumnOption, Display, FieldOption, FormFieldSpec, FormValue, InputKind, SortOption } from "./auto.js";
@@ -24,6 +29,8 @@ export interface RecordsModel {
24
29
  findOne(id: string, o?: {
25
30
  select?: Record<string, unknown>;
26
31
  }): Promise<AppRecord | null>;
32
+ /** Counts, sums, averages, least and most over the records, in groups or all together. */
33
+ aggregate(options: AggregateOptions): Promise<AggregateResult>;
27
34
  create(values: Record<string, unknown>): Promise<AppRecord>;
28
35
  update(id: string, values: Record<string, unknown>): Promise<AppRecord>;
29
36
  delete(id: string): Promise<void>;
@@ -51,6 +58,11 @@ export interface RecordsClient {
51
58
  }>;
52
59
  /** Called with a model's name whenever a write through this client changed its records; returns the unsubscribe. */
53
60
  subscribe(listener: (model: string) => void): () => void;
61
+ /**
62
+ * Called with the models that changed whenever records of any of `models` do, by anyone (live queries); returns
63
+ * the unsubscribe. One watch on the route serves every listener.
64
+ */
65
+ watch?(models: string[], listener: (models: string[]) => void): () => void;
54
66
  }
55
67
  export interface RecordsClientOptions {
56
68
  /** The app's records route; /api/records unless the app put it elsewhere. */
@@ -77,19 +89,28 @@ export interface Query<T> {
77
89
  error: ApiError | null;
78
90
  refetch(): void;
79
91
  }
80
- /** A page of a model's records. Pass `pause` to hold off (until an id is known, say). */
81
- export declare function useFindMany(model: string, options?: ReadOptions, o?: {
92
+ /** Options every read takes. */
93
+ export interface ReadHookOptions {
94
+ /** Hold off (until an id is known, say). */
82
95
  pause?: boolean;
83
- }): Query<RecordPage>;
96
+ /** Read again whenever the model's records change, whoever changes them. */
97
+ live?: boolean;
98
+ }
99
+ /**
100
+ * A page of a model's records. Pass `pause` to hold off (until an id is known, say), and `live` to read again
101
+ * whenever its records change.
102
+ */
103
+ export declare function useFindMany(model: string, options?: ReadOptions, o?: ReadHookOptions): Query<RecordPage>;
84
104
  /** One record by id, or null when there's none the caller can read. */
85
- export declare function useFindOne(model: string, id: string | null | undefined, o?: {
105
+ export declare function useFindOne(model: string, id: string | null | undefined, o?: ReadHookOptions & {
86
106
  select?: Record<string, unknown>;
87
- pause?: boolean;
88
107
  }): Query<AppRecord | null>;
89
108
  /** The first record matching, or null. */
90
- export declare function useFindFirst(model: string, options?: Omit<ReadOptions, "first" | "after">, o?: {
109
+ export declare function useFindFirst(model: string, options?: Omit<ReadOptions, "first" | "after">, o?: ReadHookOptions): Query<AppRecord | null>;
110
+ /** Groups of a model's records with their counts, sums and averages, for a chart or a report; again after a write to it. */
111
+ export declare function useAggregate(model: string, options: AggregateOptions, o?: {
91
112
  pause?: boolean;
92
- }): Query<AppRecord | null>;
113
+ }): Query<AggregateResult>;
93
114
  /** A model's description: its fields, which AutoTable and AutoForm draw from. */
94
115
  export declare function useModel(model: string): Query<ModelDescription>;
95
116
  export interface Mutation<T, A> {
@@ -127,6 +148,8 @@ export interface AutoTableOptions {
127
148
  sort?: Sort;
128
149
  /** Whether rows can be chosen for a bulk delete. */
129
150
  selectable?: boolean;
151
+ /** Show changes to the records as they happen, whoever makes them. */
152
+ live?: boolean;
130
153
  }
131
154
  export interface AutoTableRow {
132
155
  id: string;
package/dist/react.js CHANGED
@@ -10,6 +10,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
10
10
  * globals.css) and their CSS variables, so they look like the rest of the app. `@inferencebureau/apps-sdk/polaris`
11
11
  * draws the same tables and forms in Polaris web components. Both draw what `useAutoTable` and `useAutoForm` work out,
12
12
  * which a page can use to draw its own.
13
+ *
14
+ * A read given `live: true` reads again whenever its model's records change, whoever changes them: an action, a
15
+ * Shopify sync, another tab. The client keeps one watch open on the records route for every live read on the page
16
+ * (a long poll, paused while the tab is hidden), and the route answers which models changed; the read that follows
17
+ * goes through the route like any other, so it sees only what the viewer may.
13
18
  */
14
19
  import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
15
20
  import { ApiError } from "./index.js";
@@ -24,8 +29,8 @@ export function createRecordsClient(o = {}) {
24
29
  const changed = (model) => { for (const l of listeners)
25
30
  l(model); };
26
31
  const descriptions = new Map();
27
- async function call(body) {
28
- const res = await send(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
32
+ async function call(body, signal) {
33
+ const res = await send(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), ...(signal ? { signal } : {}) });
29
34
  const text = await res.text();
30
35
  let json = {};
31
36
  try {
@@ -46,6 +51,7 @@ export function createRecordsClient(o = {}) {
46
51
  return descriptions.get(name);
47
52
  },
48
53
  findMany: (options = {}) => call({ op: "findMany", model: name, options }),
54
+ aggregate: (options) => call({ op: "aggregate", model: name, options }),
49
55
  findOne: async (id, q = {}) => {
50
56
  try {
51
57
  return await call({ op: "findOne", model: name, id, ...(q.select ? { select: q.select } : {}) });
@@ -71,12 +77,73 @@ export function createRecordsClient(o = {}) {
71
77
  return { directUploadToken: up.token };
72
78
  },
73
79
  });
80
+ // Live queries: one watch for every model a listener names, asked again as soon as it answers. The cursor carries
81
+ // over when the models change, so nothing in between is missed (at worst a model is read once more).
82
+ const live = new Map();
83
+ let cursor = null;
84
+ let running = null;
85
+ // A set of models the route refused (an older SDK's route, a model it doesn't serve, a role that can't read one).
86
+ let refused = null;
87
+ const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
88
+ function rewatch() {
89
+ const key = [...new Set([...live.values()].flat())].sort().join(",");
90
+ if (running && running.key === key && !hidden())
91
+ return;
92
+ running?.abort.abort();
93
+ running = null;
94
+ if (!key || key === refused || hidden())
95
+ return;
96
+ const run = { key, abort: new AbortController() };
97
+ running = run;
98
+ void (async () => {
99
+ for (let failures = 0; running === run;) {
100
+ try {
101
+ const r = await call({ op: "changes", models: key.split(","), cursor }, run.abort.signal);
102
+ if (running !== run)
103
+ return;
104
+ cursor = r.cursor;
105
+ failures = 0;
106
+ if (r.models.length)
107
+ for (const [l, watched] of live) {
108
+ const hit = r.models.filter((m) => watched.includes(m));
109
+ if (hit.length)
110
+ l(hit);
111
+ }
112
+ }
113
+ catch (e) {
114
+ if (running !== run)
115
+ return;
116
+ if (e instanceof ApiError && [400, 403, 404, 405].includes(e.status)) {
117
+ refused = key;
118
+ running = null;
119
+ console.warn(`Live queries for ${key} are off: ${e.message}`);
120
+ return;
121
+ }
122
+ // Offline, or the route failed: try again, backing off to half a minute.
123
+ await new Promise((done) => setTimeout(done, Math.min(30_000, 1_000 * 2 ** ++failures)));
124
+ }
125
+ }
126
+ })();
127
+ }
74
128
  const models = new Map();
75
129
  return {
76
130
  model: (name) => { if (!models.has(name))
77
131
  models.set(name, model(name)); return models.get(name); },
78
132
  global: (action, params = {}) => call({ op: "global", action, params }),
79
133
  subscribe: (l) => { listeners.add(l); return () => { listeners.delete(l); }; },
134
+ watch(names, l) {
135
+ const fn = (m) => l(m);
136
+ if (!live.size && typeof document !== "undefined")
137
+ document.addEventListener("visibilitychange", rewatch);
138
+ live.set(fn, names);
139
+ rewatch();
140
+ return () => {
141
+ live.delete(fn);
142
+ if (!live.size && typeof document !== "undefined")
143
+ document.removeEventListener("visibilitychange", rewatch);
144
+ rewatch();
145
+ };
146
+ },
80
147
  };
81
148
  }
82
149
  const Context = createContext(null);
@@ -95,8 +162,11 @@ export function useRecordsClient() {
95
162
  return fallback;
96
163
  }
97
164
  const asApiError = (e) => (e instanceof ApiError ? e : new ApiError(e instanceof Error ? e.message : String(e), 0, null));
98
- /** A read that runs again when its key changes, when it's asked to, and when a write through the client changes its model. */
99
- function useQuery(model, key, read) {
165
+ /**
166
+ * A read that runs again when its key changes, when it's asked to, and when a write through the client changes its
167
+ * model; when `live`, also when anyone's does.
168
+ */
169
+ function useQuery(model, key, read, live = false) {
100
170
  const client = useRecordsClient();
101
171
  const [state, setState] = useState({ key, data: undefined, error: null, fetching: !!read });
102
172
  const [nonce, setNonce] = useState(0);
@@ -118,23 +188,33 @@ function useQuery(model, key, read) {
118
188
  }, [key, nonce, !!read]);
119
189
  useEffect(() => client.subscribe((m) => { if (m === model)
120
190
  setNonce((n) => n + 1); }), [client, model]);
191
+ const watching = live && !!read;
192
+ useEffect(() => (watching && client.watch ? client.watch([model], () => setNonce((n) => n + 1)) : undefined), [client, model, watching]);
121
193
  const refetch = useCallback(() => setNonce((n) => n + 1), []);
122
194
  return { data: state.key === key ? state.data : undefined, fetching: state.fetching, error: state.error, refetch };
123
195
  }
124
- /** A page of a model's records. Pass `pause` to hold off (until an id is known, say). */
196
+ /**
197
+ * A page of a model's records. Pass `pause` to hold off (until an id is known, say), and `live` to read again
198
+ * whenever its records change.
199
+ */
125
200
  export function useFindMany(model, options = {}, o = {}) {
126
201
  const client = useRecordsClient();
127
- return useQuery(model, `${model}:many:${JSON.stringify(options)}`, o.pause ? null : () => client.model(model).findMany(options));
202
+ return useQuery(model, `${model}:many:${JSON.stringify(options)}`, o.pause ? null : () => client.model(model).findMany(options), o.live);
128
203
  }
129
204
  /** One record by id, or null when there's none the caller can read. */
130
205
  export function useFindOne(model, id, o = {}) {
131
206
  const client = useRecordsClient();
132
- return useQuery(model, `${model}:one:${id ?? ""}:${JSON.stringify(o.select ?? null)}`, !id || o.pause ? null : () => client.model(model).findOne(id, o.select ? { select: o.select } : {}));
207
+ return useQuery(model, `${model}:one:${id ?? ""}:${JSON.stringify(o.select ?? null)}`, !id || o.pause ? null : () => client.model(model).findOne(id, o.select ? { select: o.select } : {}), o.live);
133
208
  }
134
209
  /** The first record matching, or null. */
135
210
  export function useFindFirst(model, options = {}, o = {}) {
136
211
  const client = useRecordsClient();
137
- return useQuery(model, `${model}:first:${JSON.stringify(options)}`, o.pause ? null : async () => (await client.model(model).findMany({ ...options, first: 1 })).records[0] ?? null);
212
+ return useQuery(model, `${model}:first:${JSON.stringify(options)}`, o.pause ? null : async () => (await client.model(model).findMany({ ...options, first: 1 })).records[0] ?? null, o.live);
213
+ }
214
+ /** Groups of a model's records with their counts, sums and averages, for a chart or a report; again after a write to it. */
215
+ export function useAggregate(model, options, o = {}) {
216
+ const client = useRecordsClient();
217
+ return useQuery(model, `${model}:aggregate:${JSON.stringify(options)}`, o.pause ? null : () => client.model(model).aggregate(options));
138
218
  }
139
219
  /** A model's description: its fields, which AutoTable and AutoForm draw from. */
140
220
  export function useModel(model) {
@@ -216,11 +296,14 @@ export function useAutoTable(model, o = {}) {
216
296
  ...(order ? { sort: order } : {}),
217
297
  ...(query ? { search: query } : {}),
218
298
  };
219
- const page = useFindMany(model, findOptions, { pause: !described.data });
299
+ const page = useFindMany(model, findOptions, { pause: !described.data, live: !!o.live });
220
300
  const records = page.data?.records ?? [];
221
301
  const rows = records.map((record) => ({ id: record.id, record, cells: columns.map((c) => display(c.field, record[c.name])) }));
222
- // A new page chooses nothing.
223
- useEffect(() => { setSelected(new Set()); }, [page.data]);
302
+ // A new page chooses nothing; the same page read again keeps the rows still on it chosen.
303
+ useEffect(() => {
304
+ const ids = new Set((page.data?.records ?? []).map((r) => r.id));
305
+ setSelected((s) => (s.size && [...s].some((id) => !ids.has(id)) ? new Set([...s].filter((id) => ids.has(id))) : s));
306
+ }, [page.data]);
224
307
  const allSelected = rows.length > 0 && rows.every((r) => selected.has(r.id));
225
308
  return {
226
309
  description: described.data,
package/dist/runtime.js CHANGED
@@ -178,7 +178,7 @@ function stagingApi(api, handed) {
178
178
  return (...args) => stagingApi(v.apply(target, args), handed);
179
179
  if (prop === "$model")
180
180
  return (name) => receiver[name];
181
- if (typeof prop !== "string" || prop.startsWith("$") || prop === "then" || prop === "enqueue" || prop === "enqueueMany" || prop === "shopifySync" || !v || typeof v !== "object")
181
+ if (typeof prop !== "string" || prop.startsWith("$") || prop === "then" || prop === "enqueue" || prop === "enqueueMany" || prop === "shopifySync" || prop === "files" || !v || typeof v !== "object")
182
182
  return v;
183
183
  if (!models.has(prop))
184
184
  models.set(prop, wrap(prop, v));
package/dist/test.d.ts CHANGED
@@ -16,7 +16,8 @@
16
16
  * `select` follows belongsTo, hasOne, hasMany and hasManyThrough as the API's does.
17
17
  *
18
18
  * File fields keep their files in memory: `base64` reads back as a `data:` URL, `copyURL` as the URL itself (not
19
- * fetched, size 0), and `upload`/`createUpload` tokens as the upload (a `createUpload` needs no PUT here).
19
+ * fetched, size 0), and `upload`/`createUpload` tokens as the upload (a `createUpload` needs no PUT here). The app's
20
+ * storage (`api.files`) is in memory too: a file reads back as a `data:` URL, and `reset()` empties it.
20
21
  */
21
22
  import { ApiError, type ActionModule, type Api, type AppPermissions, type AppRecord, type AppSettings, type CallerSession, type ScheduleSetting, type Job, type LogLine, type ModelSchema, type SyncRun } from "./index.js";
22
23
  type Embed = (model: string, input: string[]) => Promise<number[][]>;
package/dist/test.js CHANGED
@@ -16,7 +16,8 @@
16
16
  * `select` follows belongsTo, hasOne, hasMany and hasManyThrough as the API's does.
17
17
  *
18
18
  * File fields keep their files in memory: `base64` reads back as a `data:` URL, `copyURL` as the URL itself (not
19
- * fetched, size 0), and `upload`/`createUpload` tokens as the upload (a `createUpload` needs no PUT here).
19
+ * fetched, size 0), and `upload`/`createUpload` tokens as the upload (a `createUpload` needs no PUT here). The app's
20
+ * storage (`api.files`) is in memory too: a file reads back as a `data:` URL, and `reset()` empties it.
20
21
  */
21
22
  import { ApiError, MAX_BULK, ShopifyError, createAiClient, describeSchema, newRecordId } from "./index.js";
22
23
  import { runAction as runPhase } from "./runtime.js";
@@ -155,6 +156,64 @@ function convert(f, v, mode) {
155
156
  /** Uploads by token: `upload`'s, and `createUpload`'s as if their PUT had happened. */
156
157
  const UPLOADS = new Map();
157
158
  let uploadSeq = 0;
159
+ const STORAGE_SEGMENT = /^[A-Za-z0-9._-]+$/;
160
+ const STORAGE_TYPES = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml", pdf: "application/pdf", csv: "text/csv", txt: "text/plain", json: "application/json", zip: "application/zip" };
161
+ /** A storage path as storage.ts checks it: segments of letters, digits, `.`, `_` and `-`. */
162
+ function storagePathOf(path) {
163
+ if (typeof path !== "string")
164
+ throw new ApiError("A file's path must be a string, like exports/reviews.csv.", 400, "invalid_request");
165
+ const p = path.replace(/^\/+/, "");
166
+ if (!p || p.length > 512 || p.split("/").some((s) => !s || s === "." || s === ".." || !STORAGE_SEGMENT.test(s))) {
167
+ throw new ApiError(`A file's path is segments of letters, digits, '.', '_' and '-' joined by '/'; ${JSON.stringify(path)} isn't one.`, 400, "invalid_request");
168
+ }
169
+ return p;
170
+ }
171
+ const storageTypeOf = (given, path) => (typeof given === "string" && MIME.test(given.split(";")[0].trim()) ? given.split(";")[0].trim().toLowerCase() : STORAGE_TYPES[path.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream");
172
+ /** The app's storage in memory: files by path, read back as `data:` URLs. A role-held api can't reach it, as the API refuses it. */
173
+ function storageClient(files, scoped, now) {
174
+ const held = () => { if (scoped())
175
+ throw new ApiError("Storage is the app's own: a call held to a role can't reach it. Read or write the file from an action or a route, and hand the browser its URL.", 403, "policy_denied"); };
176
+ const fileOf = (path, b) => ({ path, access: path.startsWith("public/") ? "public" : "private", url: `data:${b.mimeType};base64,${b.base64}`, size: b.size, mimeType: b.mimeType, uploadedAt: b.uploadedAt });
177
+ return {
178
+ async put(path, body, q = {}) {
179
+ held();
180
+ const p = storagePathOf(path);
181
+ const blob = body instanceof Blob ? body : new Blob([body]);
182
+ const bytes = new Uint8Array(await blob.arrayBuffer());
183
+ let bin = "";
184
+ for (const b of bytes)
185
+ bin += String.fromCharCode(b);
186
+ const stored = { base64: btoa(bin), mimeType: storageTypeOf(q.mimeType ?? blob.type, p), size: bytes.length, uploadedAt: new Date(now()).toISOString() };
187
+ files.set(p, stored);
188
+ return fileOf(p, stored);
189
+ },
190
+ async get(path) {
191
+ held();
192
+ const p = storagePathOf(path);
193
+ const b = files.get(p);
194
+ return b ? fileOf(p, b) : null;
195
+ },
196
+ async list(q = {}) {
197
+ held();
198
+ const prefix = (q.prefix ?? "").replace(/^\/+/, "");
199
+ const first = q.first ?? 100;
200
+ if (!Number.isInteger(first) || first < 1 || first > 1000)
201
+ throw new ApiError("first is 1 to 1000.", 400, "invalid_request");
202
+ const all = [...files.keys()].filter((p) => p.startsWith(prefix)).sort((a, b) => (a.startsWith("public/") === b.startsWith("public/") ? a.localeCompare(b) : a.startsWith("public/") ? 1 : -1));
203
+ const start = q.after ? Math.max(0, all.indexOf(q.after) + 1) : 0;
204
+ const page = all.slice(start, start + first);
205
+ const last = page[page.length - 1];
206
+ return { files: page.map((p) => fileOf(p, files.get(p))), hasNextPage: start + first < all.length, endCursor: last && start + first < all.length ? last : null };
207
+ },
208
+ async delete(path) { held(); files.delete(storagePathOf(path)); },
209
+ async createUpload(path, q = {}) {
210
+ held();
211
+ const p = storagePathOf(path);
212
+ const mimeType = storageTypeOf(q.mimeType, p);
213
+ return { url: `https://uploads.test/storage/${encodeURIComponent(p)}`, method: "PUT", headers: { "content-type": mimeType }, expiresAt: new Date(now() + 3_600_000).toISOString() };
214
+ },
215
+ };
216
+ }
158
217
  const baseName = (name, fallback = "file") => (typeof name === "string" ? name.split(/[\\/]/).pop()?.trim() : "") || fallback;
159
218
  const MIME = /^[\w.+-]+\/[\w.+-]+$/;
160
219
  const mimeOf = (given) => (typeof given === "string" && MIME.test(given.trim()) ? given.trim().toLowerCase() : "application/octet-stream");
@@ -523,6 +582,18 @@ class Records {
523
582
  rows = new Map();
524
583
  seq = 0;
525
584
  last = 0;
585
+ /** Each write, in order, for `$changes`: the model, and the store the record was and is (store-owned models). */
586
+ changes = [];
587
+ changed = 0;
588
+ waiting = new Set();
589
+ /** Resolves at the next write, or after `ms`. */
590
+ nextWrite(ms) {
591
+ return new Promise((done) => {
592
+ const fire = () => { clearTimeout(t); this.waiting.delete(fire); done(); };
593
+ const t = setTimeout(fire, ms);
594
+ this.waiting.add(fire);
595
+ });
596
+ }
526
597
  constructor(models, now, embed) {
527
598
  this.models = models;
528
599
  this.now = now;
@@ -539,12 +610,22 @@ class Records {
539
610
  this.rows.set(m.name, new Map());
540
611
  return this.rows.get(m.name);
541
612
  }
542
- clear() { this.rows.clear(); }
613
+ clear() { this.rows.clear(); this.changes = []; }
543
614
  /** The records as they are, for putting back when a run's writes don't all go through (they're made together). */
544
615
  snapshot() {
545
- return new Map([...this.rows].map(([m, t]) => [m, new Map([...t].map(([id, r]) => [id, { ...r, vectors: new Map(r.vectors) }]))]));
616
+ return { rows: new Map([...this.rows].map(([m, t]) => [m, new Map([...t].map(([id, r]) => [id, { ...r, vectors: new Map(r.vectors) }]))])), changed: this.changed };
617
+ }
618
+ /** Puts the records back, and forgets the changes since, as a rolled-back transaction's history is. */
619
+ restore(s) { this.rows = s.rows; this.changes = this.changes.filter((c) => c.n <= s.changed); }
620
+ /** How many writes there have been: a `$changes` cursor. */
621
+ get written() { return this.changed; }
622
+ log(m, ...data) {
623
+ const f = storeField(m);
624
+ const key = f ? m.byName.get(f)?.key : undefined;
625
+ this.changes.push({ n: ++this.changed, model: m.name, shops: key ? data.map((d) => d?.[key]) : [] });
626
+ for (const fire of [...this.waiting])
627
+ fire();
546
628
  }
547
- restore(rows) { this.rows = rows; }
548
629
  present(m, row, vectors, only = null) {
549
630
  const out = { id: row.id };
550
631
  if (!only || only.has("createdAt"))
@@ -977,7 +1058,7 @@ class Records {
977
1058
  return [{ at: (row) => this.comparable(row, t), desc: dir === "Descending" }];
978
1059
  });
979
1060
  }
980
- /** As the API's text search: every word in one of the text fields, and the rows holding the whole phrase. */
1061
+ /** As the API's text search: every word in one of the text fields, and each row's relevance (records.ts textSearchSql). */
981
1062
  textSearch(m, rows, text) {
982
1063
  const words = searchWords(text);
983
1064
  if (!words.length)
@@ -985,10 +1066,15 @@ class Records {
985
1066
  const fields = m.fields.filter((f) => TEXT_SEARCHED.has(f.type));
986
1067
  if (!fields.length)
987
1068
  throw invalid([{ field: "search", message: `${m.name} has no text fields to search` }]);
988
- const docOf = (r) => fields.map((f) => asText(r.data[f.key])).filter((x) => x !== null).join(" ").toLowerCase();
1069
+ const docOf = (r, fs = fields) => fs.map((f) => asText(r.data[f.key])).filter((x) => x !== null).join(" ").toLowerCase();
989
1070
  const found = rows.filter((r) => { const doc = docOf(r); return words.every((w) => doc.includes(w)); });
990
- const whole = text.trim().toLowerCase();
991
- return { rows: found, phrase: new Set(found.filter((r) => docOf(r).includes(whole)).map((r) => r.id)) };
1071
+ const short = fields.filter((f) => f.type !== "richText");
1072
+ const terms = searchTerms(words);
1073
+ const score = (r) => {
1074
+ const doc = docOf(r), shortDoc = short.length && short.length < fields.length ? docOf(r, short) : null;
1075
+ return terms.reduce((n, t) => n + t.weight * (Number(t.start.test(doc)) + Number(t.whole.test(doc)) + (shortDoc === null ? 0 : Number(t.start.test(shortDoc)))), 0);
1076
+ };
1077
+ return { rows: found, score: new Map(found.map((r) => [r.id, score(r)])) };
992
1078
  }
993
1079
  async findMany(model, o = {}) {
994
1080
  const m = this.model(model);
@@ -1001,9 +1087,9 @@ class Records {
1001
1087
  const text = typeof o.search === "string" ? this.textSearch(m, rows, o.search) : null;
1002
1088
  if (text) {
1003
1089
  rows = this.sorted(m, text.rows, o.sort, o.readable);
1004
- // Unsorted, the rows holding the whole phrase come first (a stable sort keeps the default order within each).
1090
+ // Unsorted, the best matches come first (a stable sort keeps the default order within a score).
1005
1091
  if (!o.sort)
1006
- rows.sort((a, b) => Number(text.phrase.has(b.id)) - Number(text.phrase.has(a.id)));
1092
+ rows.sort((a, b) => text.score.get(b.id) - text.score.get(a.id));
1007
1093
  }
1008
1094
  else if (o.search && typeof o.search === "object") {
1009
1095
  const f = m.byName.get(o.search.field);
@@ -1042,6 +1128,157 @@ class Records {
1042
1128
  const m = this.model(model);
1043
1129
  return [...this.table(m).values()].filter((r) => this.matches(m, r, filter, { ...CTX, readable })).length;
1044
1130
  }
1131
+ /** As the API's aggregate query (records.ts aggregateRecords): the same groups, values, labels, order and problems. */
1132
+ aggregate(model, o) {
1133
+ const m = this.model(model);
1134
+ const bad = (field, message) => invalid([{ field, message }]);
1135
+ if (!o || typeof o !== "object")
1136
+ throw bad("aggregates", "must be given");
1137
+ const groupBy = o.groupBy ?? [];
1138
+ if (!Array.isArray(groupBy))
1139
+ throw bad("groupBy", 'must be a list, like ["status", { field: "createdAt", interval: "month" }]');
1140
+ if (groupBy.length > 4)
1141
+ throw bad("groupBy", "takes at most 4 fields");
1142
+ if (!o.aggregates || typeof o.aggregates !== "object" || !Object.keys(o.aggregates).length)
1143
+ throw bad("aggregates", "names at least one, like { reviews: { count: true } }");
1144
+ if (Object.keys(o.aggregates).length > 20)
1145
+ throw bad("aggregates", "takes at most 20");
1146
+ const first = o.first === undefined ? 100 : o.first;
1147
+ if (typeof first !== "number" || !Number.isInteger(first) || first < 1 || first > 1000)
1148
+ throw bad("first", "must be a whole number, 1 to 1000");
1149
+ const tz = o.timeZone ?? "UTC";
1150
+ try {
1151
+ if (typeof tz !== "string")
1152
+ throw new Error();
1153
+ new Intl.DateTimeFormat("en", { timeZone: tz });
1154
+ }
1155
+ catch {
1156
+ throw bad("timeZone", 'must be an IANA time zone, like "America/New_York"');
1157
+ }
1158
+ const value = (name, at) => {
1159
+ const f = m.byName.get(name);
1160
+ if (name === "id" || (f && f.type !== "computed" && (!GROUPED.has(f.type) || (f.type === "enum" && f.def.allowMultiple === true)))) {
1161
+ throw bad(at, name === "id" ? "id can't be grouped or aggregated" : `${name} is a ${f.type === "enum" ? "multiple-choice enum" : f.type} field, which can't be grouped or aggregated`);
1162
+ }
1163
+ if (!f && name !== "createdAt" && name !== "updatedAt")
1164
+ throw bad(`${at}.${name}`, `${m.name} has no field named ${name}`);
1165
+ try {
1166
+ return this.ref(m, name, CTX);
1167
+ }
1168
+ catch (e) {
1169
+ throw bad(`${at}.${name}`, e.message);
1170
+ }
1171
+ };
1172
+ // Each column: its name, and its value for a group's rows.
1173
+ const cols = [];
1174
+ const names = new Set();
1175
+ const read = (type, v) => (v === null || v === undefined ? null : type === "dateTime" ? new Date(String(v)).toISOString() : v);
1176
+ for (const [i, g] of groupBy.entries()) {
1177
+ const at = `groupBy.${i}`;
1178
+ const field = typeof g === "string" ? g : g && typeof g === "object" && typeof g.field === "string" ? g.field : null;
1179
+ if (!field)
1180
+ throw bad(at, "must be a field name, or { field, interval } for a dateTime");
1181
+ if (names.has(field))
1182
+ throw bad(at, `groups by ${field} twice`);
1183
+ names.add(field);
1184
+ const v = value(field, at);
1185
+ if (typeof g === "string") {
1186
+ cols.push({ name: field, of: (rows) => read(v.type, v.at(rows[0])) });
1187
+ continue;
1188
+ }
1189
+ if (!DATE_INTERVALS.includes(g.interval))
1190
+ throw bad(at, `interval is one of ${DATE_INTERVALS.join(", ")}`);
1191
+ if (v.type !== "dateTime")
1192
+ throw bad(at, `${field} isn't a dateTime, so it has no ${g.interval}s`);
1193
+ cols.push({ name: field, of: (rows) => { const x = v.at(rows[0]); return x === null || x === undefined ? null : dateLabel(String(x), g.interval, tz); } });
1194
+ }
1195
+ const groups = cols.length;
1196
+ for (const [name, spec] of Object.entries(o.aggregates)) {
1197
+ const at = `aggregates.${name}`;
1198
+ if (!/^[A-Za-z_$][\w$]*$/.test(name))
1199
+ throw bad(at, "must be a name made of letters, digits and _");
1200
+ if (names.has(name))
1201
+ throw bad(at, "is also a field it groups by; name it something else");
1202
+ names.add(name);
1203
+ const fns = spec && typeof spec === "object" ? ["count", "sum", "avg", "min", "max"].filter((k) => spec[k] !== undefined) : [];
1204
+ if (fns.length !== 1 || Object.keys(spec).length !== 1)
1205
+ throw bad(at, 'is one of { count: true }, { count: "field" }, { sum | avg | min | max: "field" }');
1206
+ const fn = fns[0];
1207
+ const arg = spec[fn];
1208
+ if (fn === "count" && arg === true) {
1209
+ cols.push({ name, of: (rows) => rows.length });
1210
+ continue;
1211
+ }
1212
+ if (typeof arg !== "string")
1213
+ throw bad(at, `${fn} names a field${fn === "count" ? ", or is true to count records" : ""}`);
1214
+ const v = value(arg, at);
1215
+ const values = (rows) => rows.map((r) => v.at(r)).filter((x) => x !== null && x !== undefined);
1216
+ if (fn === "count") {
1217
+ cols.push({ name, of: (rows) => values(rows).length });
1218
+ continue;
1219
+ }
1220
+ if ((fn === "sum" || fn === "avg") && v.type !== "number")
1221
+ throw bad(at, `${fn} needs a number field; ${arg} isn't one`);
1222
+ if (v.type === "boolean")
1223
+ throw bad(at, `${fn} can't read a boolean field`);
1224
+ cols.push({ name, of: (rows) => {
1225
+ const xs = values(rows);
1226
+ if (!xs.length)
1227
+ return null;
1228
+ if (fn === "sum" || fn === "avg") {
1229
+ const sum = xs.reduce((a, b) => a + b, 0);
1230
+ return fn === "sum" ? sum : sum / xs.length;
1231
+ }
1232
+ const pick = xs.reduce((a, b) => ((fn === "min" ? b < a : b > a) ? b : a));
1233
+ return read(v.type, pick);
1234
+ } });
1235
+ }
1236
+ const sorts = o.sort === undefined ? [] : Array.isArray(o.sort) ? o.sort : [o.sort];
1237
+ const order = [];
1238
+ for (const s of sorts) {
1239
+ if (!s || typeof s !== "object")
1240
+ throw bad("sort", 'must be an object, like { reviews: "Descending" }');
1241
+ for (const [name, dir] of Object.entries(s)) {
1242
+ const i = cols.findIndex((c) => c.name === name);
1243
+ if (i < 0)
1244
+ throw bad(`sort.${name}`, "sorts by a field it groups by or an aggregate it names");
1245
+ if (dir !== "Ascending" && dir !== "Descending")
1246
+ throw bad(`sort.${name}`, "sorts Ascending or Descending");
1247
+ order.push({ i, desc: dir === "Descending" });
1248
+ }
1249
+ }
1250
+ for (let i = 0; i < groups; i++)
1251
+ order.push({ i, desc: false });
1252
+ let rows = [...this.table(m).values()].filter((r) => this.matches(m, r, o.filter, { ...CTX, readable: o.readable }));
1253
+ if (o.search)
1254
+ rows = this.textSearch(m, rows, o.search)?.rows ?? rows;
1255
+ // Rows by their group values; with nothing to group by, one group of them all, empty or not.
1256
+ const buckets = new Map();
1257
+ if (!groups)
1258
+ buckets.set("", rows);
1259
+ for (const r of groups ? rows : []) {
1260
+ const key = JSON.stringify(cols.slice(0, groups).map((c) => c.of([r])));
1261
+ if (!buckets.has(key))
1262
+ buckets.set(key, []);
1263
+ buckets.get(key).push(r);
1264
+ }
1265
+ const out = [...buckets.values()].map((rs) => cols.map((c) => c.of(rs)));
1266
+ out.sort((a, b) => {
1267
+ for (const { i, desc } of order) {
1268
+ const x = a[i], y = b[i];
1269
+ if (x === y)
1270
+ continue;
1271
+ if (x === null)
1272
+ return 1;
1273
+ if (y === null)
1274
+ return -1;
1275
+ const c = x < y ? -1 : 1;
1276
+ return desc ? -c : c;
1277
+ }
1278
+ return 0;
1279
+ });
1280
+ return { groups: out.slice(0, first).map((vals) => Object.fromEntries(cols.map((c, i) => [c.name, vals[i]]))), hasMore: out.length > first };
1281
+ }
1045
1282
  // ---- select (records.ts: planOf, attach) ----
1046
1283
  /** A select checked against the model, as records.ts's planOf checks it; null when unset. */
1047
1284
  plan(m, select, path = "select", depth = 0) {
@@ -1316,6 +1553,7 @@ class Records {
1316
1553
  const row = { id: id ?? `rec_${String(++this.seq).padStart(6, "0")}`, createdAt: at, updatedAt: at, data: p.data, vectors: new Map() };
1317
1554
  await this.vectorize(m, row, p.vectors, null);
1318
1555
  this.table(m).set(row.id, row);
1556
+ this.log(m, row.data);
1319
1557
  return this.present(m, row, true);
1320
1558
  }
1321
1559
  async update(model, id, values) {
@@ -1328,12 +1566,15 @@ class Records {
1328
1566
  row.data = p.data;
1329
1567
  row.updatedAt = this.stamp();
1330
1568
  await this.vectorize(m, row, p.vectors, before);
1569
+ this.log(m, before, row.data);
1331
1570
  return this.present(m, row, true);
1332
1571
  }
1333
1572
  delete(model, id) {
1334
1573
  const m = this.model(model);
1335
- if (!this.table(m).delete(id))
1574
+ const row = this.table(m).get(id);
1575
+ if (!row || !this.table(m).delete(id))
1336
1576
  throw notFound(`There's no ${m.name} with id ${id}.`);
1577
+ this.log(m, row.data);
1337
1578
  }
1338
1579
  checkPassword(model, id, password, field = "password") {
1339
1580
  const m = this.model(model);
@@ -1346,7 +1587,40 @@ class Records {
1346
1587
  }
1347
1588
  const OPS = ["equals", "notEquals", "in", "notIn", "lessThan", "lessThanOrEqual", "greaterThan", "greaterThanOrEqual", "isSet", "startsWith", "contains"];
1348
1589
  const TEXT_SEARCHED = new Set(["string", "richText", "email", "url", "enum"]);
1590
+ /** What an aggregate groups by (records.ts BTREE_TYPES and dateTime), and how it buckets dates. */
1591
+ const GROUPED = new Set(["string", "email", "url", "color", "enum", "number", "boolean", "dateTime", "belongsTo"]);
1592
+ const DATE_INTERVALS = ["hour", "day", "week", "month", "quarter", "year"];
1593
+ /** A date's bucket in a time zone, labelled as Postgres's to_char labels it in records.ts. */
1594
+ function dateLabel(iso, interval, timeZone) {
1595
+ const d = new Date(iso);
1596
+ if (Number.isNaN(d.getTime()))
1597
+ return null;
1598
+ const parts = Object.fromEntries(new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", hourCycle: "h23" }).formatToParts(d).map((p) => [p.type, p.value]));
1599
+ const { year: y, month: mo, day: da, hour: h } = parts;
1600
+ if (interval === "hour")
1601
+ return `${y}-${mo}-${da}T${h}:00`;
1602
+ if (interval === "day")
1603
+ return `${y}-${mo}-${da}`;
1604
+ if (interval === "week") {
1605
+ const local = new Date(Date.UTC(Number(y), Number(mo) - 1, Number(da)));
1606
+ local.setUTCDate(local.getUTCDate() - ((local.getUTCDay() + 6) % 7));
1607
+ return local.toISOString().slice(0, 10);
1608
+ }
1609
+ if (interval === "month")
1610
+ return `${y}-${mo}`;
1611
+ if (interval === "quarter")
1612
+ return `${y}-Q${Math.ceil(Number(mo) / 3)}`;
1613
+ return y;
1614
+ }
1349
1615
  const searchWords = (text) => text.toLowerCase().match(/[\p{L}\p{N}]+(?:['’.@-][\p{L}\p{N}]+)*/gu) ?? [];
1616
+ /** A search's relevance terms, as records.ts searchTerms: each word, and the first eight in order (weight 3), where each starts a word and where it's a whole word. */
1617
+ function searchTerms(words) {
1618
+ const ranked = words.slice(0, 8).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
1619
+ const terms = ranked.map((re) => ({ weight: 1, re }));
1620
+ if (ranked.length > 1)
1621
+ terms.push({ weight: 3, re: ranked.join("[^\\p{L}\\p{N}_]+") });
1622
+ return terms.map((t) => ({ weight: t.weight, start: new RegExp(`(?<![\\p{L}\\p{N}_])${t.re}`, "u"), whole: new RegExp(`(?<![\\p{L}\\p{N}_])${t.re}(?![\\p{L}\\p{N}_])`, "u") }));
1623
+ }
1350
1624
  const embeddingModelOf = (f) => (typeof f.def.embeddingModel === "string" && f.def.embeddingModel ? f.def.embeddingModel : DEFAULT_EMBEDDING_MODEL);
1351
1625
  function sourceText(m, f, data) {
1352
1626
  const names = Array.isArray(f.def.source) ? f.def.source.map(String) : [];
@@ -2017,6 +2291,7 @@ export function createTestApp(o = {}) {
2017
2291
  const environment = o.environment ?? "development";
2018
2292
  const shopify = shopifyMock();
2019
2293
  const ai = aiMock(o.embed);
2294
+ const storage = new Map();
2020
2295
  const jobs = [];
2021
2296
  const logs = [];
2022
2297
  const perms = readPermissions(o.permissions);
@@ -2224,6 +2499,7 @@ export function createTestApp(o = {}) {
2224
2499
  findOne: async (id, o = {}) => findVisible(name, id, readOf(), wire(o.select), readable),
2225
2500
  findMany: async (q = {}) => store.findMany(name, narrow(wire(q))),
2226
2501
  findFirst: async (q = {}) => (await store.findMany(name, { ...narrow(wire(q)), first: 1 })).records[0] ?? null,
2502
+ aggregate: async (q) => store.aggregate(name, narrow(wire(q))),
2227
2503
  search: async (field, near, q = {}) => (await store.findMany(name, { ...narrow(wire(q)), search: { field, near } })),
2228
2504
  // As through the API: the model's create, update or delete action when it has one, else a direct write.
2229
2505
  create: async (values) => {
@@ -2371,10 +2647,44 @@ export function createTestApp(o = {}) {
2371
2647
  out.push(await queue(action, e.params, { ...q, ...(e.id ? { id: e.id } : {}) }));
2372
2648
  return out;
2373
2649
  };
2650
+ // What changed since a cursor, as the API answers it: waiting up to `wait` seconds for a write when none has.
2651
+ const $changes = async (q) => {
2652
+ if (q.wait !== undefined && !(q.wait >= 0 && q.wait <= 25))
2653
+ throw new ApiError("wait must be 0 to 25 seconds", 400, "invalid_request");
2654
+ if (!Array.isArray(q.models) || !q.models.length)
2655
+ throw new ApiError("Name the models to watch.", 400, "invalid_request");
2656
+ const watched = q.models.map((n) => store.model(n));
2657
+ if (isScoped(scope))
2658
+ for (const m of watched)
2659
+ readFilter(perms, scope, m);
2660
+ if (!q.cursor)
2661
+ return { cursor: String(store.written), models: [] };
2662
+ const after = Number(q.cursor);
2663
+ if (!Number.isSafeInteger(after))
2664
+ throw new ApiError("That cursor isn't one a watch handed out; start again without one.", 400, "invalid_request");
2665
+ const names = new Set(watched.map((m) => m.name));
2666
+ const since = () => {
2667
+ const models = new Set();
2668
+ for (const c of store.changes) {
2669
+ if (c.n <= after || !names.has(c.model))
2670
+ continue;
2671
+ if (scope.shop && c.shops.length && !c.shops.includes(scope.shop))
2672
+ continue;
2673
+ models.add(c.model);
2674
+ }
2675
+ return { cursor: String(store.written), models: [...models].sort() };
2676
+ };
2677
+ let r = since();
2678
+ for (const end = Date.now() + (q.wait ?? 0) * 1000; !r.models.length && Date.now() < end; r = since())
2679
+ await store.nextWrite(end - Date.now());
2680
+ return r;
2681
+ };
2374
2682
  const made = new Proxy({}, {
2375
2683
  get(_t, prop) {
2376
2684
  if (prop === "$global")
2377
2685
  return $global;
2686
+ if (prop === "$changes")
2687
+ return $changes;
2378
2688
  if (prop === "$model")
2379
2689
  return (name) => made[name];
2380
2690
  if (prop === "enqueue")
@@ -2387,6 +2697,8 @@ export function createTestApp(o = {}) {
2387
2697
  return (role, session) => apiFor({ ...scope, role: roleOf(role), session: session ? sessionOf(session) : scope.session });
2388
2698
  if (prop === "shopifySync")
2389
2699
  return shopifySync(scope);
2700
+ if (prop === "files")
2701
+ return storageClient(storage, () => !!scope.role, o.now ?? Date.now);
2390
2702
  if (typeof prop !== "string" || prop === "then")
2391
2703
  return undefined;
2392
2704
  if (!clients.has(prop))
@@ -2585,7 +2897,7 @@ export function createTestApp(o = {}) {
2585
2897
  shopify,
2586
2898
  ai,
2587
2899
  logs,
2588
- reset() { store.clear(); jobs.length = 0; scheduled.clear(); syncRuns.length = 0; logs.length = 0; shopify.calls.length = 0; ai.calls.length = 0; },
2900
+ reset() { store.clear(); storage.clear(); jobs.length = 0; scheduled.clear(); syncRuns.length = 0; logs.length = 0; shopify.calls.length = 0; ai.calls.length = 0; },
2589
2901
  };
2590
2902
  }
2591
2903
  // ---- loading an app's folder ----
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "description": "The SDK an Inference Bureau app's code imports: action helpers, metadata types, the records API client, React hooks with AutoTable and AutoForm, and a test harness for its actions.",
5
5
  "license": "UNLICENSED",
6
6
  "keywords": [