@authoric/handler-sdk 6.3.0 → 6.4.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.
Files changed (2) hide show
  1. package/handler-sdk.d.ts +112 -7
  2. package/package.json +1 -1
package/handler-sdk.d.ts CHANGED
@@ -524,6 +524,35 @@ interface HandlerApp {
524
524
  branding(): Promise<AppBranding>;
525
525
  }
526
526
 
527
+ /**
528
+ * One person of an org, as `sdk.people` returns them: their uid (what a row's user reference, such as
529
+ * `author_uid`, holds) and their name. `email` is present only when the app's owner turned on
530
+ * showing members' email (App settings › Sign-in › People).
531
+ */
532
+ interface Person {
533
+ uid: string;
534
+ /** First and last name together, or null when the person gave neither. */
535
+ name: string | null;
536
+ fname: string | null;
537
+ lname: string | null;
538
+ email?: string | null;
539
+ }
540
+
541
+ /**
542
+ * The people of the orgs this run reaches: inside the app, the caller's org; for the app's owner from
543
+ * outside (a job, the owner's agents), every org it reaches. Never an email unless the owner turned
544
+ * that on, never anyone outside those orgs.
545
+ */
546
+ interface HandlerPeople {
547
+ /** A page of the people, in the order they joined, searched by name prefix. Pass `after: page.nextCursor` for the next. */
548
+ list(options?: { search?: string; after?: string | null; limit?: number }): Promise<{ items: Person[]; nextCursor: string | null }>;
549
+ /**
550
+ * The names of these people (up to 100 uids), for showing who did something: a uid of someone
551
+ * outside the reach, or of nobody, is simply absent from `items`.
552
+ */
553
+ names(userUids: string[]): Promise<{ items: Person[] }>;
554
+ }
555
+
527
556
  interface ImportCsvOptions {
528
557
  /** Destination table. */
529
558
  table: string;
@@ -554,7 +583,9 @@ interface ImportCsvOptions {
554
583
  ignoreUnknownColumns?: boolean;
555
584
  /**
556
585
  * What to do with a row holding a value the table cannot store (bad enum member, over-long
557
- * string, non-numeric number, out-of-range integer).
586
+ * string, non-numeric number, out-of-range integer), or a reference that names no row: every
587
+ * row's references are looked up before anything is written, and each miss is an error with its
588
+ * line and column, on a dry run too.
558
589
  * - `"abort"` (default): import nothing and throw with the offending rows listed.
559
590
  * - `"skip"`: import the clean rows and report the rest in `skippedRows` / `errors`.
560
591
  * A bad value is never silently repaired or replaced under either setting. Neither setting
@@ -569,10 +600,12 @@ interface ImportCsvOptions {
569
600
  /**
570
601
  * Upsert: a UNIQUE column each file row is matched on, typically the id the rows had in the
571
602
  * system they come from (`"shopify_id"`). A row whose value matches an existing row updates it;
572
- * the rest are created; so running the same file twice changes nothing the second time. The
573
- * column must be unique (alone or per org) and mapped from the file. Two file rows with the same
574
- * value are refused (`CSV_DUPLICATE_MATCH`, 422) with their lines. A dry run reports
575
- * `match: { inserts, updates, skipped }`.
603
+ * the rest are created; so running the same file twice changes nothing the second time. A matched
604
+ * row the file leaves as it is gets no write and no change event: the result counts it as
605
+ * `unchanged`, apart from `updated`. The column must be unique (alone or per org) and mapped from
606
+ * the file. Two file rows with the same value are refused (`CSV_DUPLICATE_MATCH`, 422) with their
607
+ * lines. A dry run reports `match: { inserts, updates, unchanged, skipped }`. A handler that imports
608
+ * with matchOn needs `<table>:update` in its route's allowed actions as well as `<table>:create`.
576
609
  */
577
610
  matchOn?: string;
578
611
  /** With `matchOn`: `"update"` (default) updates a matched row, `"skip"` leaves it as it is. */
@@ -1225,6 +1258,36 @@ interface HandlerSdk {
1225
1258
  /** Alias of {@link HandlerSdk.withTransaction}. */
1226
1259
  transaction<T>(work: (txSdk: HandlerSdk) => Promise<T>): Promise<T>;
1227
1260
 
1261
+ // ── As the caller ───────────────────────────────────────────────────────
1262
+
1263
+ /**
1264
+ * The same SDK, with every call decided AS THE CALLER (6.4.0). A handler behind a route is
1265
+ * otherwise decided by the route's allowed actions: the code chooses what it reaches, so a
1266
+ * member-only rule (isMember, isOwner, fieldEquals in a policy) never applies inside it. Through
1267
+ * `sdk.asCaller()`, the route's allowed actions stay the ceiling (a call it does not list is still
1268
+ * refused), and then the caller's own policy decides each call, row conditions included, exactly
1269
+ * as the same call made directly from the app:
1270
+ *
1271
+ * - a list, a page or an aggregate holds only the rows the caller may read;
1272
+ * - a row the caller may not read answers exactly as a uid no row has (an update or delete
1273
+ * changes nothing), so a handler never confirms that a hidden row exists;
1274
+ * - a write must satisfy the caller's conditions (an isOwner create is the caller's own), and a
1275
+ * reference may name only a row the caller could read (`ROW_REFERENCE_NOT_FOUND` otherwise);
1276
+ * - each call needs the caller's own grant, not only the route's.
1277
+ *
1278
+ * Use it in any handler over a member-scoped table, so the platform applies the rule instead of
1279
+ * the handler re-checking membership. It shares the open transaction and the dry run.
1280
+ * `sql` / `query` are not offered on it (`SDK_AS_CALLER_UNSUPPORTED`): raw SQL runs inside the
1281
+ * database, where no row rule is judged. In a scheduled job every call is already decided by the
1282
+ * job's principal, so `asCaller()` changes nothing there. A dry run does not judge the caller.
1283
+ *
1284
+ * @example
1285
+ * const me = sdk.asCaller();
1286
+ * const messages = await me.readList("messages", { filters: { channel_uid: data.channelUid } });
1287
+ * await me.create("messages", { channel_uid: data.channelUid, body: data.body, user_uid: ctx.user.uid });
1288
+ */
1289
+ asCaller(): HandlerSdk;
1290
+
1228
1291
  /**
1229
1292
  * Guard a block with an idempotency key so retries with the same key return
1230
1293
  * the stored result instead of running the work twice.
@@ -1540,6 +1603,18 @@ interface HandlerSdk {
1540
1603
  * return { logo: brand.logoUrl, primary: brand.colors.light.primary ?? "#111111" };
1541
1604
  */
1542
1605
  app: HandlerApp;
1606
+
1607
+ /**
1608
+ * The people of the orgs this run reaches, by uid and name: a row's user reference to a name,
1609
+ * without a grant on the users table. Read-only.
1610
+ *
1611
+ * @example
1612
+ * const posts = await sdk.readList("posts", { filters: { channel_uid: channelUid } });
1613
+ * const { items } = await sdk.people.names(posts.map((p) => p.author_uid));
1614
+ * const nameOf = new Map(items.map((p) => [p.uid, p.name]));
1615
+ * return posts.map((p) => ({ ...p, author: nameOf.get(p.author_uid) ?? "Former member" }));
1616
+ */
1617
+ people: HandlerPeople;
1543
1618
  }
1544
1619
 
1545
1620
  /**
@@ -1974,6 +2049,11 @@ interface StorageFolder {
1974
2049
  path: string;
1975
2050
  depth: number;
1976
2051
  storage_uid: string | null;
2052
+ /**
2053
+ * The group this folder belongs to, or `null`. Inside the app only the people in the group's
2054
+ * members table reach the folder and everything below it; to anyone else it is a missing folder.
2055
+ */
2056
+ group: StorageFolderGroup | null;
1977
2057
  /**
1978
2058
  * Present only on the app owner's own items (no org), and only to the owner's side (the
1979
2059
  * owner's agents and jobs): which of the app's organizations see this item, and whether that
@@ -1987,6 +2067,20 @@ interface StorageFolder {
1987
2067
  sharedByOwner?: true;
1988
2068
  }
1989
2069
 
2070
+ /**
2071
+ * A folder's group: a row of a group table of the app (a project, a class, a channel) and the members
2072
+ * table that references it and `users`. Only the people in that row's members table, and the app's
2073
+ * owner, reach the folder.
2074
+ */
2075
+ interface StorageFolderGroup {
2076
+ /** The group table, such as `projects`. */
2077
+ table: string;
2078
+ /** The group row's uid. */
2079
+ row_uid: string | null;
2080
+ /** The members table, such as `project_members`. */
2081
+ members: string;
2082
+ }
2083
+
1990
2084
  /**
1991
2085
  * Which of the app's organizations see one of the owner's folders or files. Only me (`only_me`,
1992
2086
  * the default), every organization including later ones (`all`), or the listed ones (`orgs`).
@@ -2184,10 +2278,21 @@ interface HandlerStorage {
2184
2278
  },
2185
2279
  ): Promise<{ confirmed: number; files: StorageFile[] }>;
2186
2280
 
2187
- /** Create ONE folder under `parentUid` (omit for the root). `name` is a single segment. */
2281
+ /**
2282
+ * Create ONE folder under `parentUid` (omit for the root). `name` is a single segment.
2283
+ *
2284
+ * `group` makes it a group's folder: only the people in that group's members table (and the app's
2285
+ * owner) reach it and what is below it. Inside the app the caller must be in the group (another
2286
+ * is `ROW_REFERENCE_NOT_FOUND`, as for a row that does not exist); only the owner changes it later.
2287
+ */
2188
2288
  createFolder(
2189
2289
  storageUid: string,
2190
- options: { name: string; parentUid?: string | null },
2290
+ options: {
2291
+ name: string;
2292
+ parentUid?: string | null;
2293
+ /** The group row (its uid or key) of `table`, and the members table that says who is in it. */
2294
+ group?: { table: string; rowUid: string; members: string } | null;
2295
+ },
2191
2296
  ): Promise<StorageFolder>;
2192
2297
 
2193
2298
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@authoric/handler-sdk",
3
- "version": "6.3.0",
3
+ "version": "6.4.0",
4
4
  "description": "TypeScript types for Authoric handlers: the sdk and ctx a handler is given.",
5
5
  "license": "MIT",
6
6
  "types": "handler-sdk.d.ts",