@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.
- package/handler-sdk.d.ts +112 -7
- 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.
|
|
573
|
-
*
|
|
574
|
-
*
|
|
575
|
-
*
|
|
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
|
-
/**
|
|
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: {
|
|
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
|
/**
|