@inferencebureau/apps-sdk 0.15.1 → 0.15.2

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
@@ -803,10 +803,11 @@ export type Api = ModelClients & {
803
803
  forShop(shop: string): Api;
804
804
  /**
805
805
  * The same API held to a role in accessControl/permissions.ib.ts: only what the role is granted, through its
806
- * filters, with `session` standing in for `{ $session: "userId" | "customerId" }`. A Shopify session's and a proxy
806
+ * filters, with `session` standing in for `{ $session: "userId" | "customerId" | "accountId" }`. Several roles
807
+ * (`["signed-in", "account-admin"]`) are held to the union of their grants. A Shopify session's and a proxy
807
808
  * request's `api` already are.
808
809
  */
809
- asRole(role: string, session?: CallerSession): Api;
810
+ asRole(role: string | string[], session?: CallerSession): Api;
810
811
  /** Shopify sync on demand: one store, some or all of its synced models, everything or what changed since a date. */
811
812
  shopifySync: ShopifySync;
812
813
  /**
@@ -936,7 +937,8 @@ export interface Changes {
936
937
  export interface CallerSession {
937
938
  userId?: string | null;
938
939
  customerId?: string | null;
939
- customerRecordId?: string | null;
940
+ customerRecordId?: string | null; /** The account the user acts in (a web app's `$session: "accountId"`). */
941
+ accountId?: string | null;
940
942
  }
941
943
  export interface EnqueueOptions {
942
944
  /** The record a model's action works on. */
@@ -975,8 +977,8 @@ export interface ClientOptions {
975
977
  fetch?: typeof fetch;
976
978
  /** Narrows every call to one store (see `Api.forShop`). */
977
979
  shop?: string;
978
- /** Holds every call to a role in permissions.ib.ts (see `Api.asRole`). */
979
- role?: string;
980
+ /** Holds every call to a role in permissions.ib.ts, or to several roles' grants together (see `Api.asRole`). */
981
+ role?: string | string[];
980
982
  session?: CallerSession;
981
983
  }
982
984
  /** The app's API. In an app's deployment every option comes from its environment variables. */
@@ -1476,9 +1478,12 @@ export interface Logger {
1476
1478
  warn(message: string, data?: unknown): void;
1477
1479
  error(message: string, data?: unknown): void;
1478
1480
  }
1479
- export interface ActionContext {
1480
- /** What the caller passed. A model action's fields may be at the top level or under the model's name. */
1481
- params: Record<string, unknown>;
1481
+ export interface ActionContext<P = Record<string, unknown>> {
1482
+ /**
1483
+ * What the caller passed. A model action's fields may be at the top level or under the model's name. Typed from the
1484
+ * file's `export const params` with `ActionRun<DeclaredParams<typeof params>>` (the declaration `as const`).
1485
+ */
1486
+ params: P;
1482
1487
  /** The record the action works on: the stored one, or a new, empty one for a create. Null in a global action. */
1483
1488
  record: ActionRecord;
1484
1489
  /**
@@ -1518,9 +1523,9 @@ export interface ActionCaller {
1518
1523
  customerId?: string | null;
1519
1524
  customerRecordId?: string | null;
1520
1525
  }
1521
- export type ActionRun = (ctx: ActionContext) => unknown | Promise<unknown>;
1522
- export type ActionOnSuccess = (ctx: ActionContext) => void | Promise<void>;
1523
- export type GlobalActionRun = (ctx: Omit<ActionContext, "record"> & {
1526
+ export type ActionRun<P = Record<string, unknown>> = (ctx: ActionContext<P>) => unknown | Promise<unknown>;
1527
+ export type ActionOnSuccess<P = Record<string, unknown>> = (ctx: ActionContext<P>) => void | Promise<void>;
1528
+ export type GlobalActionRun<P = Record<string, unknown>> = (ctx: Omit<ActionContext<P>, "record"> & {
1524
1529
  record: null;
1525
1530
  }) => unknown | Promise<unknown>;
1526
1531
  export interface ActionOptions {
@@ -1565,6 +1570,43 @@ export interface ParamDef {
1565
1570
  /** array: each item. */
1566
1571
  items?: ParamDef;
1567
1572
  }
1573
+ /**
1574
+ * What an action's `export const params` declares, as types, for `run` to read them typed:
1575
+ *
1576
+ * export const params = { note: { type: "string" }, notify: { type: "boolean", required: true } } as const satisfies ActionParams;
1577
+ * export const run: ActionRun<DeclaredParams<typeof params>> = async ({ params }) => { params.note; // string | undefined
1578
+ *
1579
+ * Nothing checks them at run time: a caller can still send anything.
1580
+ */
1581
+ export type DeclaredParams<D> = Flat<{
1582
+ -readonly [K in keyof D as D[K] extends {
1583
+ required: true;
1584
+ } ? K : never]: DeclaredValue<D[K]>;
1585
+ } & {
1586
+ -readonly [K in keyof D as D[K] extends {
1587
+ required: true;
1588
+ } ? never : K]?: DeclaredValue<D[K]>;
1589
+ }>;
1590
+ type DeclaredValue<P> = P extends {
1591
+ type: "string" | "dateTime";
1592
+ } ? string : P extends {
1593
+ type: "number";
1594
+ } ? number : P extends {
1595
+ type: "boolean";
1596
+ } ? boolean : P extends {
1597
+ type: "enum";
1598
+ options: readonly (infer O)[];
1599
+ } ? O : P extends {
1600
+ type: "enum";
1601
+ } ? string : P extends {
1602
+ type: "object";
1603
+ properties: infer Q;
1604
+ } ? DeclaredParams<Q> : P extends {
1605
+ type: "array";
1606
+ items: infer I;
1607
+ } ? DeclaredValue<I>[] : P extends {
1608
+ type: "array";
1609
+ } ? unknown[] : any;
1568
1610
  export interface CaptureOptions {
1569
1611
  /** Searchable in Sentry. Values are cut to 200 characters. */
1570
1612
  tags?: Record<string, string | number | boolean | null | undefined>;
package/dist/index.js CHANGED
@@ -143,9 +143,10 @@ export function createClient(o = {}) {
143
143
  const f = o.fetch ?? fetch;
144
144
  const base = `${url}/v1/apps/${encodeURIComponent(app)}/environments/${encodeURIComponent(environment)}`;
145
145
  // The scope only narrows what the token may do; Inference Bureau applies it (and refuses a malformed one).
146
+ const role = Array.isArray(o.role) ? o.role.join(",") : o.role;
146
147
  const scope = {
147
- ...(o.shop ? { "x-ib-shop": o.shop } : {}), ...(o.role ? { "x-ib-role": o.role } : {}),
148
- ...(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 } : {}) }) } : {}),
148
+ ...(o.shop ? { "x-ib-shop": o.shop } : {}), ...(role ? { "x-ib-role": role } : {}),
149
+ ...(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 } : {}), ...(o.session.accountId ? { accountId: o.session.accountId } : {}) }) } : {}),
149
150
  };
150
151
  /**
151
152
  * A call with a JSON body (or none); `raw` sends bytes as they are, with their type when known. A call turned away
package/dist/test.js CHANGED
@@ -1823,12 +1823,14 @@ function syncItem(model, o, shop) {
1823
1823
  const fields = Array.isArray(o.fields) ? Object.fromEntries(o.fields.map((x) => [x.key, x.value])) : isObj(o.fields) ? o.fields : {};
1824
1824
  return { model, shopifyId: id, updatedAt, values: { sh_id: id, sh_shop: shop, sh_type: str(o.type), sh_handle: str(o.handle), sh_display_name: str(o.display_name), sh_fields: fields, sh_updated_at: updatedAt } };
1825
1825
  }
1826
- const FULL_ACCESS = { shop: null, role: null, session: { userId: null, customerId: null, customerRecordId: null } };
1826
+ const FULL_ACCESS = { shop: null, role: null, session: { userId: null, customerId: null, customerRecordId: null, accountId: null } };
1827
+ /** The roles a scope is held to: `role` holds several comma-separated, as the API's x-ib-role does. */
1828
+ const rolesOf = (s) => (s.role ? s.role.split(",") : []);
1827
1829
  const isScoped = (s) => !!s.shop || !!s.role;
1828
1830
  const CUSTOMER_ROLE = "storefront-customers";
1829
1831
  const PERMISSIONS_PATH = "accessControl/permissions.ib.ts";
1830
1832
  const ROLE = /^[a-z][a-z0-9-]{0,63}$/;
1831
- const sessionOf = (s = {}) => ({ userId: s.userId ?? null, customerId: s.customerId ?? null, customerRecordId: s.customerRecordId ?? null });
1833
+ const sessionOf = (s = {}) => ({ userId: s.userId ?? null, customerId: s.customerId ?? null, customerRecordId: s.customerRecordId ?? null, accountId: s.accountId ?? null });
1832
1834
  const denied = (message) => new ApiError(message, 403, "policy_denied");
1833
1835
  /** The field holding a record's store, or null when the model isn't store-owned. */
1834
1836
  function storeField(m) {
@@ -1862,7 +1864,7 @@ const customerGid = (id) => (id.startsWith("gid://") ? id : `gid://shopify/Custo
1862
1864
  /** A condition no record meets. */
1863
1865
  const NOTHING = { id: { in: [] } };
1864
1866
  function customerFilter(m, scope) {
1865
- if (scope.role !== CUSTOMER_ROLE)
1867
+ if (!rolesOf(scope).includes(CUSTOMER_ROLE))
1866
1868
  return undefined;
1867
1869
  const f = customerField(m);
1868
1870
  if (!f)
@@ -1922,7 +1924,7 @@ function fillValue(v, scope, missing) {
1922
1924
  const keys = Object.keys(v);
1923
1925
  if (keys.length === 1 && keys[0] === "$session") {
1924
1926
  const name = v.$session;
1925
- const value = name === "shop" ? scope.shop : name === "userId" || name === "customerId" || name === "customerRecordId" ? scope.session[name] : null;
1927
+ const value = name === "shop" ? scope.shop : name === "userId" || name === "customerId" || name === "customerRecordId" || name === "accountId" ? scope.session[name] : null;
1926
1928
  if (value === null || value === undefined)
1927
1929
  missing();
1928
1930
  return value ?? null;
@@ -1947,19 +1949,28 @@ function fill(f, scope) {
1947
1949
  function roleFilter(perms, scope, model, op, what) {
1948
1950
  if (!scope.role)
1949
1951
  return {};
1950
- const r = perms.roles.get(scope.role);
1951
- let g;
1952
- if (r) {
1953
- if (model === null)
1954
- g = "action" in op && r.globalActions[op.action] === true;
1955
- else {
1956
- const m = r.models[model];
1957
- g = "read" in op ? (m?.read ?? r.default.read) : (m?.actions[op.action] ?? r.default.action);
1952
+ // Several roles are held to the union of their grants: everything when any grants it outright, else the OR of their filters.
1953
+ const filters = [];
1954
+ const roles = rolesOf(scope);
1955
+ for (const role of roles) {
1956
+ const r = perms.roles.get(role);
1957
+ let g;
1958
+ if (r) {
1959
+ if (model === null)
1960
+ g = "action" in op && r.globalActions[op.action] === true;
1961
+ else {
1962
+ const m = r.models[model];
1963
+ g = "read" in op ? (m?.read ?? r.default.read) : (m?.actions[op.action] ?? r.default.action);
1964
+ }
1958
1965
  }
1966
+ if (g === true)
1967
+ return {};
1968
+ if (g)
1969
+ filters.push(fill(g.filter, scope));
1959
1970
  }
1960
- if (!g)
1961
- throw denied(`The ${scope.role} role can't ${what}.${perms.problem ? ` (${perms.problem})` : ` Grant it in ${PERMISSIONS_PATH}.`}`);
1962
- return g === true ? {} : fill(g.filter, scope);
1971
+ if (!filters.length)
1972
+ throw denied(`The ${roles.join(", ")} role${roles.length === 1 ? "" : "s"} can't ${what}.${perms.problem ? ` (${perms.problem})` : ` Grant it in ${PERMISSIONS_PATH}.`}`);
1973
+ return filters.length === 1 ? filters[0] : { OR: filters };
1963
1974
  }
1964
1975
  const combine = (...fs) => {
1965
1976
  const list = fs.filter((f) => !!f && Object.keys(f).length > 0);
@@ -1990,7 +2001,7 @@ function scopedValues(scope, m, values) {
1990
2001
  throw denied(`This call is for ${scope.shop}; it can't write ${m.name} records of another store.`);
1991
2002
  out = { ...out, [f]: scope.shop };
1992
2003
  }
1993
- const c = scope.role === CUSTOMER_ROLE ? customerField(m) : null;
2004
+ const c = rolesOf(scope).includes(CUSTOMER_ROLE) ? customerField(m) : null;
1994
2005
  if (c && c.field !== "id") {
1995
2006
  const mine = c.by === "record" ? scope.session.customerRecordId : scope.session.customerId ? customerGid(scope.session.customerId) : null;
1996
2007
  if (!mine)
@@ -2004,7 +2015,7 @@ function scopedValues(scope, m, values) {
2004
2015
  /** An update's values: the store field may stay as it is, never become another store, and a customer's record stays theirs. */
2005
2016
  function scopedUpdate(scope, m, values) {
2006
2017
  const f = scope.shop ? storeField(m) : null;
2007
- const c = scope.role === CUSTOMER_ROLE ? customerField(m)?.field : null;
2018
+ const c = rolesOf(scope).includes(CUSTOMER_ROLE) ? customerField(m)?.field : null;
2008
2019
  if (!(f && f in values) && !(c && c !== "id" && c in values))
2009
2020
  return values;
2010
2021
  return scopedValues(scope, m, values);
@@ -2375,7 +2386,7 @@ export function createTestApp(o = {}) {
2375
2386
  const m = store.model(w.model);
2376
2387
  // A run about one store writes that store's records of a store-owned model, as through the API.
2377
2388
  const f = shop ? storeField(m) : null;
2378
- const own = { shop, role: null, session: { userId: null, customerId: null, customerRecordId: null } };
2389
+ const own = { shop, role: null, session: { userId: null, customerId: null, customerRecordId: null, accountId: null } };
2379
2390
  if (w.op !== "create" && f && !(await findVisible(m.name, w.id, { [f]: { equals: shop } })))
2380
2391
  throw notFound(`There's no ${m.name} with id ${w.id}.`);
2381
2392
  if (w.op === "delete")
@@ -2617,9 +2628,10 @@ export function createTestApp(o = {}) {
2617
2628
  const apis = new Map();
2618
2629
  /** A role's name as the API takes it; a malformed one is refused, never ignored (ignoring it would widen the call). */
2619
2630
  const roleOf = (role) => {
2620
- if (!ROLE.test(role))
2621
- throw new ApiError("x-ib-role must be a role's name.", 400, "invalid_request");
2622
- return role;
2631
+ const names = [...new Set((Array.isArray(role) ? role : role.split(",")).map((r) => r.trim()).filter(Boolean))];
2632
+ if (!names.length || names.some((r) => !ROLE.test(r)))
2633
+ throw new ApiError("x-ib-role must be a role's name, or several separated by commas.", 400, "invalid_request");
2634
+ return names.join(",");
2623
2635
  };
2624
2636
  /** The API for a scope: every store or one (`forShop`), as the environment or held to a role (`asRole`). */
2625
2637
  const apiFor = (scope) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.15.1",
3
+ "version": "0.15.2",
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": [