@authoric/handler-sdk 6.3.1 → 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 +103 -2
  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;
@@ -1229,6 +1258,36 @@ interface HandlerSdk {
1229
1258
  /** Alias of {@link HandlerSdk.withTransaction}. */
1230
1259
  transaction<T>(work: (txSdk: HandlerSdk) => Promise<T>): Promise<T>;
1231
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
+
1232
1291
  /**
1233
1292
  * Guard a block with an idempotency key so retries with the same key return
1234
1293
  * the stored result instead of running the work twice.
@@ -1544,6 +1603,18 @@ interface HandlerSdk {
1544
1603
  * return { logo: brand.logoUrl, primary: brand.colors.light.primary ?? "#111111" };
1545
1604
  */
1546
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;
1547
1618
  }
1548
1619
 
1549
1620
  /**
@@ -1978,6 +2049,11 @@ interface StorageFolder {
1978
2049
  path: string;
1979
2050
  depth: number;
1980
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;
1981
2057
  /**
1982
2058
  * Present only on the app owner's own items (no org), and only to the owner's side (the
1983
2059
  * owner's agents and jobs): which of the app's organizations see this item, and whether that
@@ -1991,6 +2067,20 @@ interface StorageFolder {
1991
2067
  sharedByOwner?: true;
1992
2068
  }
1993
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
+
1994
2084
  /**
1995
2085
  * Which of the app's organizations see one of the owner's folders or files. Only me (`only_me`,
1996
2086
  * the default), every organization including later ones (`all`), or the listed ones (`orgs`).
@@ -2188,10 +2278,21 @@ interface HandlerStorage {
2188
2278
  },
2189
2279
  ): Promise<{ confirmed: number; files: StorageFile[] }>;
2190
2280
 
2191
- /** 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
+ */
2192
2288
  createFolder(
2193
2289
  storageUid: string,
2194
- 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
+ },
2195
2296
  ): Promise<StorageFolder>;
2196
2297
 
2197
2298
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@authoric/handler-sdk",
3
- "version": "6.3.1",
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",