@classytic/arc-involvement 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+import { PermissionCheck } from "@classytic/arc/permissions";
+
+//#region src/index.d.ts
+interface InvolvementScopeOptions {
+  /** May this caller see ALL rows (HQ oversight)? Default: never. */
+  readonly isOversight?: (req: InvolvementScopeRequest) => boolean | Promise<boolean>;
+  /** Cast the org id for the filter (e.g. Mongo ObjectId). Default: identity. */
+  readonly castId?: (orgId: string) => unknown;
+  /**
+   * Org header name. MUST match the host's scope-resolution header
+   * (`createApp` scope `options.header`) — this filter is the visibility
+   * boundary, and a mismatched header would scope against a different org
+   * than the rest of the request pipeline. Default: `x-organization-id`
+   * (arc's scope default).
+   */
+  readonly header?: string;
+}
+interface InvolvementScopeRequest {
+  headers?: Record<string, unknown>;
+  scope?: {
+    organizationId?: string;
+  };
+}
+/**
+ * Involvement `$or` filter over `fields` for a party caller, or `null` when
+ * the caller has oversight (no scope — company-wide) or no org context.
+ *
+ * Header-first resolution, matching HQ-gate semantics (`x-organization-id`
+ * over session scope) so oversight checks and scoping agree on the org.
+ *
+ * Use in raw `/stats` / `/export` handlers:
+ * `const s = await resolveInvolvementScope(req, fields, opts); if (s) Object.assign(match, s);`
+ */
+declare function resolveInvolvementScope(req: InvolvementScopeRequest, fields: readonly string[], options?: InvolvementScopeOptions): Promise<Record<string, unknown> | null>;
+/**
+ * Wrap a resource's `list` `PermissionCheck`: run the base view gate, then
+ * RETURN the involvement scope as `filters`. Arc merges a PermissionResult's
+ * `filters` into `request._policyFilters`, which QueryResolver folds into the
+ * list query (`$or` supported). Returning the filter is the supported
+ * contract — mutating `request.metadata` is NOT read on the list path.
+ *
+ * ```ts
+ * list: involvementListScope(view, ['senderBranch', 'receiverBranch'], {
+ *   isOversight: isHeadOffice,
+ *   castId: (id) => new Types.ObjectId(id),
+ * }),
+ * ```
+ */
+declare function involvementListScope(base: PermissionCheck, fields: readonly string[], options?: InvolvementScopeOptions): PermissionCheck;
+//#endregion
+export { InvolvementScopeOptions, InvolvementScopeRequest, involvementListScope, resolveInvolvementScope };

package/dist/index.mjs

@@ -0,0 +1,55 @@
+//#region src/index.ts
+/**
+* Involvement `$or` filter over `fields` for a party caller, or `null` when
+* the caller has oversight (no scope — company-wide) or no org context.
+*
+* Header-first resolution, matching HQ-gate semantics (`x-organization-id`
+* over session scope) so oversight checks and scoping agree on the org.
+*
+* Use in raw `/stats` / `/export` handlers:
+* `const s = await resolveInvolvementScope(req, fields, opts); if (s) Object.assign(match, s);`
+*/
+async function resolveInvolvementScope(req, fields, options = {}) {
+	const headerName = options.header ?? "x-organization-id";
+	const orgId = req.headers?.[headerName] ?? req.scope?.organizationId;
+	if (!orgId) return null;
+	if (options.isOversight && await options.isOversight(req)) return null;
+	const id = options.castId ? options.castId(String(orgId)) : String(orgId);
+	return { $or: fields.map((f) => ({ [f]: id })) };
+}
+/**
+* Wrap a resource's `list` `PermissionCheck`: run the base view gate, then
+* RETURN the involvement scope as `filters`. Arc merges a PermissionResult's
+* `filters` into `request._policyFilters`, which QueryResolver folds into the
+* list query (`$or` supported). Returning the filter is the supported
+* contract — mutating `request.metadata` is NOT read on the list path.
+*
+* ```ts
+* list: involvementListScope(view, ['senderBranch', 'receiverBranch'], {
+*   isOversight: isHeadOffice,
+*   castId: (id) => new Types.ObjectId(id),
+* }),
+* ```
+*/
+function involvementListScope(base, fields, options = {}) {
+	return async (ctx) => {
+		const result = await base(ctx);
+		if (!(typeof result === "boolean" ? result : result?.granted)) return result;
+		const scope = await resolveInvolvementScope(ctx.request, fields, options);
+		if (!scope) return result;
+		const baseFilters = typeof result === "object" && result !== null ? result.filters : void 0;
+		if (!baseFilters) return {
+			granted: true,
+			filters: scope
+		};
+		return {
+			granted: true,
+			filters: Object.keys(baseFilters).some((key) => key in scope) ? { $and: [baseFilters, scope] } : {
+				...baseFilters,
+				...scope
+			}
+		};
+	};
+}
+//#endregion
+export { involvementListScope, resolveInvolvementScope };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@classytic/arc-involvement",
+  "version": "0.1.0",
+  "description": "Multi-party (involvement) visibility scoping for @classytic/arc — ERP-standard $or party filters with oversight bypass and base-permission filter composition",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
+  },
+  "peerDependencies": {
+    "@classytic/arc": ">=2.20.0"
+  },
+  "keywords": [
+    "arc",
+    "fastify",
+    "multi-tenant",
+    "visibility",
+    "scoping",
+    "classytic"
+  ],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-ecosystem.git",
+    "directory": "packages/arc-involvement"
+  }
+}