@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/internal/api-client/operationTransportSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operationTransportSurface.js","sourceRoot":"","sources":["operationTransportSurface.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAEjB,MAAM,iCAAiC,CAAC;AAazC,SAAS,mBAAmB,CAAC,SAAwB;IACnD,OAAO,CACL,CAAC,SAAS,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,KAAK,kBAAkB;QACzE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,KAAK,CACrD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,kBAAkB,CAChD,CACF,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B,CAAC,SAAwB;IAC5D,OAAO,CACL,SAAS,CAAC,gBAAgB,KAAK,0BAA0B;QACzD,SAAS,CAAC,IAAI,KAAK,gBAAgB;QACnC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,KAAK,CACrD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,kBAAkB,CAChD,CACF,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,uEAAuE;AACvE,gDAAgD;AAChD,SAAS,6BAA6B,CAAC,SAAwB;IAC7D,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtE,OAAO,CACL,CAAC,SAAS,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,KAAK,kBAAkB;QACzE,CAAC,SAAS,CAAC,qBAAqB,EAAE,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC;QACpD,gBAAgB,CAAC,MAAM,GAAG,CAAC;QAC3B,gBAAgB,CAAC,KAAK,CACpB,CAAC,MAAM,EAAE,EAAE,CACT,SAAS,CAAC,kBAAkB,EAAE,CAAC,MAAM,CAAC,KAAK,0BAA0B,CACxE,CACF,CAAC;AACJ,CAAC;AAED,MAAM,iBAAiB,GAEnB;IACF,aAAa,EAAE,4BAA4B;IAC3C,cAAc,EAAE,6BAA6B;IAC7C,IAAI,EAAE,mBAAmB;CAC1B,CAAC;AAEF,MAAM,aAAa,GAAwD;IACzE,aAAa,EAAE,gBAAgB;IAC/B,cAAc,EAAE,iBAAiB;IACjC,IAAI,EAAE,MAAM;CACb,CAAC;AAEF,MAAM,WAAW,GAAyC;IACxD,eAAe;IACf,gBAAgB;IAChB,MAAM;CACP,CAAC;AAEF,MAAM,UAAU,iCAAiC,CAC/C,SAAwB;IAExB,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,SAAwB;IAExB,MAAM,OAAO,GAAG,iCAAiC,CAAC,SAAS,CAAC,CAAC;IAC7D,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,SAAwB,EACxB,OAAkC;IAElC,IAAI,yBAAyB,CAAC,SAAS,CAAC,KAAK,OAAO,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CACjB,eAAe,aAAa,CAAC,OAAO,CAAC,yBAAyB,SAAS,CAAC,EAAE,EAAE,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import {\n  BinaryBodySchema,\n  type HttpOperation,\n} from \"@tearleads/validators/operation\";\n\n/**\n * The low-level transport surfaces the API client implements. Every\n * registered HTTP operation must resolve to exactly one surface; the\n * registry-wide guard in operationTransportSurface.test.ts fails when an\n * operation shape is claimed by none or by more than one.\n */\nexport type OperationTransportSurface =\n  | \"binaryRequest\"\n  | \"binaryResponse\"\n  | \"json\";\n\nfunction supportsJsonSurface(operation: HttpOperation): boolean {\n  return (\n    (operation.requestMediaType ?? \"application/json\") === \"application/json\" &&\n    Object.values(operation.responseMediaTypes ?? {}).every(\n      (mediaType) => mediaType === \"application/json\",\n    )\n  );\n}\n\nfunction supportsBinaryRequestSurface(operation: HttpOperation): boolean {\n  return (\n    operation.requestMediaType === \"application/octet-stream\" &&\n    operation.body === BinaryBodySchema &&\n    Object.values(operation.responseMediaTypes ?? {}).every(\n      (mediaType) => mediaType === \"application/json\",\n    )\n  );\n}\n\n// Empty-success statuses are excluded until the binary envelope models them;\n// a binary operation that declares one must fail classification loudly\n// instead of silently losing transport support.\nfunction supportsBinaryResponseSurface(operation: HttpOperation): boolean {\n  const responseStatuses = Object.keys(operation.responses).map(Number);\n  return (\n    (operation.requestMediaType ?? \"application/json\") === \"application/json\" &&\n    (operation.emptyResponseStatuses?.length ?? 0) === 0 &&\n    responseStatuses.length > 0 &&\n    responseStatuses.every(\n      (status) =>\n        operation.responseMediaTypes?.[status] === \"application/octet-stream\",\n    )\n  );\n}\n\nconst surfacePredicates: Readonly<\n  Record<OperationTransportSurface, (operation: HttpOperation) => boolean>\n> = {\n  binaryRequest: supportsBinaryRequestSurface,\n  binaryResponse: supportsBinaryResponseSurface,\n  json: supportsJsonSurface,\n};\n\nconst surfaceLabels: Readonly<Record<OperationTransportSurface, string>> = {\n  binaryRequest: \"binary request\",\n  binaryResponse: \"binary response\",\n  json: \"JSON\",\n};\n\nconst allSurfaces: readonly OperationTransportSurface[] = [\n  \"binaryRequest\",\n  \"binaryResponse\",\n  \"json\",\n];\n\nexport function matchedOperationTransportSurfaces(\n  operation: HttpOperation,\n): readonly OperationTransportSurface[] {\n  return allSurfaces.filter((surface) => surfacePredicates[surface](operation));\n}\n\nexport function operationTransportSurface(\n  operation: HttpOperation,\n): OperationTransportSurface | null {\n  const matched = matchedOperationTransportSurfaces(operation);\n  return matched.length === 1 ? (matched[0] ?? null) : null;\n}\n\nexport function requireOperationTransportSurface(\n  operation: HttpOperation,\n  surface: OperationTransportSurface,\n): void {\n  if (operationTransportSurface(operation) !== surface) {\n    throw new TypeError(\n      `Unsupported ${surfaceLabels[surface]} transport operation: ${operation.id}`,\n    );\n  }\n}\n"]}

package/internal/api-client/principalHistoryRequest.js

@@ -0,0 +1,90 @@
+import { decodeJsonOperationResponse } from "./operationResponse.js";
+import { PrincipalHistoryRequestContext } from "./principalHistoryRequestContext.js";
+/** Retry only an explicit, validated response proving the operation rolled back. */
+export async function principalHistoryRequest(runtime, input) {
+    const { path, method } = input;
+    const context = input.context ??
+        new PrincipalHistoryRequestContext(runtime, method, path, input.options);
+    const options = context.options;
+    const progress = { previous: undefined, unchanged: 0 };
+    while (true) {
+        if (context.cancelled())
+            return context.failure();
+        context.beforeRequest();
+        const decoded = await readResponse(runtime, context, input);
+        if (!decoded.ok && context.restartReadAfterRenewal())
+            continue;
+        if (!decoded.ok)
+            return decoded;
+        if (decoded.data.status === 202) {
+            context.afterPreparation();
+            const failure = await continuePreparation(decoded.data.data, progress);
+            if (failure)
+                return runtime.responseRequest.reportFailure({
+                    ...failure,
+                    method,
+                    options,
+                    path,
+                    status: 202,
+                    statusText: decoded.data.statusText,
+                });
+            continue;
+        }
+        if (decoded.data.status !== 200 || !input.validator(decoded.data.data))
+            return runtime.responseRequest.reportFailure({
+                kind: "shape",
+                message: `Invalid principal policy response for ${path}`,
+                method,
+                options,
+                path,
+                status: decoded.data.status,
+                statusText: decoded.data.statusText,
+            });
+        return { ok: true, data: decoded.data.data };
+    }
+}
+async function readResponse(runtime, context, input) {
+    const response = await runtime.responseRequest(input.path, input.method, input.body, context.options, [], input.operation);
+    // Authentication rejection precedes the workflow, so renewal does not make
+    // this write's outcome uncertain. Reads may restart after a known renewal.
+    if (!response.ok && response.kind === "http" && response.status === 401)
+        return response;
+    if (context.cancelled())
+        return context.failure(response.ok ? response.data : undefined);
+    if (!response.ok)
+        return response;
+    const decoded = await decodeJsonOperationResponse(runtime.responseRequest, input.operation, response.data, input.path, context.options);
+    if (context.cancelled())
+        return context.failure(response.data);
+    if (!decoded.ok)
+        return decoded;
+    return {
+        ok: true,
+        data: { ...decoded.data, statusText: response.data.statusText },
+    };
+}
+async function continuePreparation(data, progress) {
+    const token = typeof data === "object" &&
+        data !== null &&
+        "progressToken" in data &&
+        typeof data.progressToken === "string"
+        ? data.progressToken
+        : undefined;
+    if (token === undefined)
+        return {
+            kind: "shape",
+            message: "Principal preparation progress is missing",
+        };
+    progress.unchanged = token === progress.previous ? progress.unchanged + 1 : 0;
+    progress.previous = token;
+    if (progress.unchanged >= 2)
+        return {
+            code: "principal_history_preparation_stalled",
+            kind: "http",
+            message: "Principal history preparation did not advance; retry later",
+        };
+    // The next round checks cancellation and identity again before any request.
+    await new Promise((resolve) => setTimeout(resolve, progress.unchanged ? 250 : 25));
+    return null;
+}
+//# sourceMappingURL=principalHistoryRequest.js.map

package/internal/api-client/principalHistoryRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRequest.js","sourceRoot":"","sources":["principalHistoryRequest.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonOperation } from \"@tearleads/validators/operation\";\nimport type { ApiRequestRuntime } from \"./apiRequestRuntime\";\nimport { decodeJsonOperationResponse } from \"./operationResponse\";\nimport { PrincipalHistoryRequestContext } from \"./principalHistoryRequestContext\";\nimport type { HttpMethod, RequestResult, RequestResultOptions } from \"./types\";\n\n/** Retry only an explicit, validated response proving the operation rolled back. */\nexport async function principalHistoryRequest<T>(\n  runtime: ApiRequestRuntime,\n  input: {\n    readonly path: string;\n    readonly validator: (value: unknown) => value is T;\n    readonly method: HttpMethod;\n    readonly body?: string;\n    readonly options?: RequestResultOptions;\n    readonly operation: JsonOperation;\n    readonly context?: PrincipalHistoryRequestContext;\n  },\n): Promise<RequestResult<T>> {\n  const { path, method } = input;\n  const context =\n    input.context ??\n    new PrincipalHistoryRequestContext(runtime, method, path, input.options);\n  const options = context.options;\n  const progress: PreparationProgress = { previous: undefined, unchanged: 0 };\n  while (true) {\n    if (context.cancelled()) return context.failure();\n    context.beforeRequest();\n    const decoded = await readResponse(runtime, context, input);\n    if (!decoded.ok && context.restartReadAfterRenewal()) continue;\n    if (!decoded.ok) return decoded;\n    if (decoded.data.status === 202) {\n      context.afterPreparation();\n      const failure = await continuePreparation(decoded.data.data, progress);\n      if (failure)\n        return runtime.responseRequest.reportFailure({\n          ...failure,\n          method,\n          options,\n          path,\n          status: 202,\n          statusText: decoded.data.statusText,\n        });\n      continue;\n    }\n    if (decoded.data.status !== 200 || !input.validator(decoded.data.data))\n      return runtime.responseRequest.reportFailure({\n        kind: \"shape\",\n        message: `Invalid principal policy response for ${path}`,\n        method,\n        options,\n        path,\n        status: decoded.data.status,\n        statusText: decoded.data.statusText,\n      });\n    return { ok: true, data: decoded.data.data };\n  }\n}\n\nasync function readResponse(\n  runtime: ApiRequestRuntime,\n  context: PrincipalHistoryRequestContext,\n  input: {\n    readonly path: string;\n    readonly method: HttpMethod;\n    readonly body?: string;\n    readonly operation: JsonOperation;\n  },\n) {\n  const response = await runtime.responseRequest(\n    input.path,\n    input.method,\n    input.body,\n    context.options,\n    [],\n    input.operation,\n  );\n  // Authentication rejection precedes the workflow, so renewal does not make\n  // this write's outcome uncertain. Reads may restart after a known renewal.\n  if (!response.ok && response.kind === \"http\" && response.status === 401)\n    return response;\n  if (context.cancelled())\n    return context.failure(response.ok ? response.data : undefined);\n  if (!response.ok) return response;\n  const decoded = await decodeJsonOperationResponse(\n    runtime.responseRequest,\n    input.operation,\n    response.data,\n    input.path,\n    context.options,\n  );\n  if (context.cancelled()) return context.failure(response.data);\n  if (!decoded.ok) return decoded;\n  return {\n    ok: true as const,\n    data: { ...decoded.data, statusText: response.data.statusText },\n  };\n}\n\ninterface PreparationProgress {\n  previous: string | undefined;\n  unchanged: number;\n}\n\nasync function continuePreparation(\n  data: unknown,\n  progress: PreparationProgress,\n): Promise<{\n  readonly kind: \"shape\" | \"http\";\n  readonly message: string;\n  readonly code?: string;\n} | null> {\n  const token =\n    typeof data === \"object\" &&\n    data !== null &&\n    \"progressToken\" in data &&\n    typeof data.progressToken === \"string\"\n      ? data.progressToken\n      : undefined;\n  if (token === undefined)\n    return {\n      kind: \"shape\",\n      message: \"Principal preparation progress is missing\",\n    };\n  progress.unchanged = token === progress.previous ? progress.unchanged + 1 : 0;\n  progress.previous = token;\n  if (progress.unchanged >= 2)\n    return {\n      code: \"principal_history_preparation_stalled\",\n      kind: \"http\",\n      message: \"Principal history preparation did not advance; retry later\",\n    };\n  // The next round checks cancellation and identity again before any request.\n  await new Promise<void>((resolve) =>\n    setTimeout(resolve, progress.unchanged ? 250 : 25),\n  );\n  return null;\n}\n"]}

package/internal/api-client/principalHistoryRequestContext.js

@@ -0,0 +1,67 @@
+/** Keep continuations within their authentication context without hiding commit uncertainty. */
+export class PrincipalHistoryRequestContext {
+    runtime;
+    method;
+    path;
+    options;
+    token;
+    submitted = false;
+    renewedRead = false;
+    restartedRead = false;
+    constructor(runtime, method, path, options) {
+        this.runtime = runtime;
+        this.method = method;
+        this.path = path;
+        this.token = runtime.getAuthToken();
+        this.options = {
+            ...options,
+            retryOnSessionExpired: options?.retryOnSessionExpired === false ? false : "renew-only",
+            onSessionRenewed: () => {
+                if (method === "GET" && !options?.signal?.aborted) {
+                    this.token = runtime.getAuthToken();
+                    this.renewedRead = true;
+                }
+            },
+        };
+    }
+    cancelled() {
+        return (this.options.signal?.aborted === true ||
+            this.runtime.getAuthToken() !== this.token);
+    }
+    beforeRequest() {
+        this.submitted = this.method !== "GET";
+    }
+    afterPreparation() {
+        this.submitted = false;
+    }
+    afterReadPage() {
+        // A completed page is forward progress. A later page may renew again,
+        // while repeated 401s within one page still cannot loop indefinitely.
+        this.renewedRead = false;
+        this.restartedRead = false;
+    }
+    restartReadAfterRenewal() {
+        if (!this.renewedRead || this.restartedRead || this.cancelled())
+            return false;
+        this.restartedRead = true;
+        return true;
+    }
+    failure(response) {
+        void response?.body?.cancel().catch(() => { });
+        return this.runtime.responseRequest.reportFailure({
+            code: this.submitted
+                ? "principal_history_outcome_unknown"
+                : "principal_history_context_changed",
+            kind: this.submitted ? "outcome-unknown" : "cancelled",
+            message: this.submitted
+                ? "Policy request may have committed; refresh before retrying"
+                : "Principal history request was cancelled",
+            method: this.method,
+            options: { ...this.options, reportErrors: false },
+            path: this.path,
+            status: null,
+            statusText: "",
+        });
+    }
+}
+//# sourceMappingURL=principalHistoryRequestContext.js.map

package/internal/api-client/principalHistoryRequestContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalHistoryRequestContext.js","sourceRoot":"","sources":["principalHistoryRequestContext.ts"],"names":[],"mappings":"AAGA,gGAAgG;AAChG,MAAM,OAAO,8BAA8B;IAQtB;IACA;IACA;IATV,OAAO,CAAuB;IAC/B,KAAK,CAAgB;IACrB,SAAS,GAAG,KAAK,CAAC;IAClB,WAAW,GAAG,KAAK,CAAC;IACpB,aAAa,GAAG,KAAK,CAAC;IAE9B,YACmB,OAA0B,EAC1B,MAAkB,EAClB,IAAY,EAC7B,OAAyC;QAHxB,YAAO,GAAP,OAAO,CAAmB;QAC1B,WAAM,GAAN,MAAM,CAAY;QAClB,SAAI,GAAJ,IAAI,CAAQ;QAG7B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG;YACb,GAAG,OAAO;YACV,qBAAqB,EACnB,OAAO,EAAE,qBAAqB,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY;YACjE,gBAAgB,EAAE,GAAG,EAAE;gBACrB,IAAI,MAAM,KAAK,KAAK,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;oBAClD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;oBACpC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBAC1B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAED,SAAS;QACP,OAAO,CACL,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI;YACrC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,IAAI,CAAC,KAAK,CAC3C,CAAC;IACJ,CAAC;IAED,aAAa;QACX,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC;IACzC,CAAC;IAED,gBAAgB;QACd,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;IAED,aAAa;QACX,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC7B,CAAC;IAED,uBAAuB;QACrB,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,SAAS,EAAE;YAC7D,OAAO,KAAK,CAAC;QACf,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,QAAmB;QACzB,KAAK,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC;YAChD,IAAI,EAAE,IAAI,CAAC,SAAS;gBAClB,CAAC,CAAC,mCAAmC;gBACrC,CAAC,CAAC,mCAAmC;YACvC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW;YACtD,OAAO,EAAE,IAAI,CAAC,SAAS;gBACrB,CAAC,CAAC,4DAA4D;gBAC9D,CAAC,CAAC,yCAAyC;YAC7C,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE;YACjD,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI;YACZ,UAAU,EAAE,EAAE;SACf,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import type { ApiRequestRuntime } from \"./apiRequestRuntime\";\nimport type { HttpMethod, RequestFailure, RequestResultOptions } from \"./types\";\n\n/** Keep continuations within their authentication context without hiding commit uncertainty. */\nexport class PrincipalHistoryRequestContext {\n  readonly options: RequestResultOptions;\n  private token: string | null;\n  private submitted = false;\n  private renewedRead = false;\n  private restartedRead = false;\n\n  constructor(\n    private readonly runtime: ApiRequestRuntime,\n    private readonly method: HttpMethod,\n    private readonly path: string,\n    options: RequestResultOptions | undefined,\n  ) {\n    this.token = runtime.getAuthToken();\n    this.options = {\n      ...options,\n      retryOnSessionExpired:\n        options?.retryOnSessionExpired === false ? false : \"renew-only\",\n      onSessionRenewed: () => {\n        if (method === \"GET\" && !options?.signal?.aborted) {\n          this.token = runtime.getAuthToken();\n          this.renewedRead = true;\n        }\n      },\n    };\n  }\n\n  cancelled(): boolean {\n    return (\n      this.options.signal?.aborted === true ||\n      this.runtime.getAuthToken() !== this.token\n    );\n  }\n\n  beforeRequest(): void {\n    this.submitted = this.method !== \"GET\";\n  }\n\n  afterPreparation(): void {\n    this.submitted = false;\n  }\n\n  afterReadPage(): void {\n    // A completed page is forward progress. A later page may renew again,\n    // while repeated 401s within one page still cannot loop indefinitely.\n    this.renewedRead = false;\n    this.restartedRead = false;\n  }\n\n  restartReadAfterRenewal(): boolean {\n    if (!this.renewedRead || this.restartedRead || this.cancelled())\n      return false;\n    this.restartedRead = true;\n    return true;\n  }\n\n  failure(response?: Response): RequestFailure {\n    void response?.body?.cancel().catch(() => {});\n    return this.runtime.responseRequest.reportFailure({\n      code: this.submitted\n        ? \"principal_history_outcome_unknown\"\n        : \"principal_history_context_changed\",\n      kind: this.submitted ? \"outcome-unknown\" : \"cancelled\",\n      message: this.submitted\n        ? \"Policy request may have committed; refresh before retrying\"\n        : \"Principal history request was cancelled\",\n      method: this.method,\n      options: { ...this.options, reportErrors: false },\n      path: this.path,\n      status: null,\n      statusText: \"\",\n    });\n  }\n}\n"]}

package/internal/api-client/principalPolicyPages.d.ts

@@ -0,0 +1,20 @@
+import type { PrincipalPolicyBundleResponse, PrincipalPolicyPageResponse } from "../validators/response/index.js";
+import type { ApiRequestRuntime } from "./apiRequestRuntime.js";
+import type { RequestResult, RequestResultOptions } from "./types.js";
+export type PrincipalPolicyPageCurrent = Omit<PrincipalPolicyBundleResponse, "previousStates">;
+/** A transport position. Only the caller can authenticate the saved prefix. */
+export interface PrincipalPolicyPageResume {
+    readonly current: PrincipalPolicyPageCurrent;
+    readonly afterVersion: number;
+}
+export interface PrincipalPolicyPageReadOptions extends RequestResultOptions {
+    /** Select an exact signed head even before its first page has been read. */
+    readonly stateHash?: string | undefined;
+    /** Transport offset for a caller-authenticated prefix; requires stateHash. */
+    readonly afterVersion?: number | undefined;
+    readonly resume?: PrincipalPolicyPageResume | undefined;
+}
+/** Pull one page at a time; the caller owns verification and durable admission. */
+export declare function readPrincipalPolicyPages(runtime: ApiRequestRuntime, principalType: "group" | "organization", principalId: string, options: PrincipalPolicyPageReadOptions): AsyncGenerator<RequestResult<PrincipalPolicyPageResponse>, void>;
+/** Full-bundle adapter for consumers that have not adopted durable staging. */
+export declare function collectPrincipalPolicyPages(runtime: ApiRequestRuntime, principalType: "group" | "organization", principalId: string, options: RequestResultOptions): Promise<PrincipalPolicyBundleResponse | null>;

package/internal/api-client/principalPolicyPages.js

@@ -0,0 +1,181 @@
+import { serializeKeyingCanonicalJson } from "../crypto/index.js";
+import { getPrincipalPolicyOperation } from "../validators/operation/index.js";
+import { principalHistoryRequest } from "./principalHistoryRequest.js";
+import { PrincipalHistoryRequestContext } from "./principalHistoryRequestContext.js";
+import { getPrincipalPolicy } from "./routes/principals/policy.js";
+function currentArtifacts(page) {
+    return {
+        currentState: page.currentState,
+        currentPayload: page.currentPayload,
+        currentProjection: page.currentProjection,
+        currentGrants: page.currentGrants,
+        currentMemberEnvelopes: page.currentMemberEnvelopes,
+    };
+}
+function validResume(principalType, principalId, resume, stateHash) {
+    const state = resume.current.currentState;
+    return (Number.isSafeInteger(resume.afterVersion) &&
+        resume.afterVersion >= 0 &&
+        resume.afterVersion < state.version &&
+        state.principalType === principalType &&
+        state.principalId === principalId &&
+        (stateHash === undefined || state.stateHash === stateHash));
+}
+function readResume(input) {
+    if (input === undefined)
+        return undefined;
+    try {
+        const page = {
+            ...input.current,
+            previousStates: [],
+            historyPage: { afterVersion: input.afterVersion, nextAfterVersion: null },
+        };
+        if (!getPrincipalPolicy.isResponse(page))
+            return undefined;
+        const current = structuredClone(currentArtifacts(page));
+        return {
+            current,
+            afterVersion: page.historyPage.afterVersion,
+            bytes: serializeKeyingCanonicalJson(current),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function validPage(page, expected) {
+    const { afterVersion } = expected;
+    const lastVersion = afterVersion + page.previousStates.length;
+    return (page.currentState.principalType === expected.principalType &&
+        page.currentState.principalId === expected.principalId &&
+        (expected.stateHash === undefined ||
+            page.currentState.stateHash === expected.stateHash) &&
+        (expected.pinnedBytes === undefined ||
+            expected.bytes === expected.pinnedBytes) &&
+        page.historyPage.afterVersion === afterVersion &&
+        lastVersion < page.currentState.version &&
+        page.previousStates.every(({ state }, index) => state.version === afterVersion + index + 1 &&
+            state.principalId === expected.principalId &&
+            state.principalType === expected.principalType) &&
+        (page.historyPage.nextAfterVersion === null
+            ? lastVersion === page.currentState.version - 1
+            : lastVersion > afterVersion &&
+                lastVersion < page.currentState.version - 1 &&
+                page.historyPage.nextAfterVersion === lastVersion));
+}
+function preparePrincipalPolicyRead(runtime, principalType, principalId, options) {
+    const query = options.stateHash === undefined
+        ? {}
+        : {
+            afterVersion: options.afterVersion ?? 0,
+            stateHash: options.stateHash,
+        };
+    const basePath = getPrincipalPolicy.path(principalType, principalId);
+    const failure = (message) => ({
+        ok: false,
+        failure: pageFailure(runtime, basePath, options, message, null),
+    });
+    if (options.afterVersion !== undefined &&
+        (options.stateHash === undefined ||
+            options.resume !== undefined ||
+            !Number.isSafeInteger(options.afterVersion)))
+        return failure("Initial principal history cursor requires one exact head");
+    if (!getPrincipalPolicyOperation.query.safeParse(query).success)
+        return failure("Invalid requested principal history head");
+    const resume = readResume(options.resume);
+    if (options.resume !== undefined &&
+        (!resume ||
+            !validResume(principalType, principalId, resume, options.stateHash)))
+        return failure("Invalid saved principal history position");
+    return {
+        ok: true,
+        firstPath: getPrincipalPolicy.path(principalType, principalId, query),
+        afterVersion: options.afterVersion ?? 0,
+        resume,
+    };
+}
+/** Pull one page at a time; the caller owns verification and durable admission. */
+export async function* readPrincipalPolicyPages(runtime, principalType, principalId, options) {
+    const position = preparePrincipalPolicyRead(runtime, principalType, principalId, options);
+    if (!position.ok) {
+        yield position.failure;
+        return;
+    }
+    const { firstPath, resume } = position;
+    const context = new PrincipalHistoryRequestContext(runtime, "GET", firstPath, options);
+    let pinned = resume?.current;
+    let pinnedBytes = resume?.bytes;
+    let afterVersion = resume?.afterVersion ?? position.afterVersion;
+    while (true) {
+        const path = pinned
+            ? getPrincipalPolicy.path(principalType, principalId, {
+                afterVersion,
+                stateHash: pinned.currentState.stateHash,
+            })
+            : firstPath;
+        const result = await principalHistoryRequest(runtime, {
+            path,
+            validator: getPrincipalPolicy.isResponse,
+            method: "GET",
+            operation: getPrincipalPolicyOperation,
+            options,
+            context,
+        });
+        if (!result.ok) {
+            yield result;
+            return;
+        }
+        const page = result.data;
+        const artifacts = currentArtifacts(page);
+        const bytes = serializeKeyingCanonicalJson(artifacts);
+        const valid = validPage(page, {
+            principalType,
+            principalId,
+            stateHash: options.stateHash,
+            pinnedBytes,
+            bytes,
+            afterVersion,
+        });
+        if (!valid) {
+            yield pageFailure(runtime, path, options, "Principal history page changed its head, order, or cursor", 200);
+            return;
+        }
+        pinned ??= structuredClone(artifacts);
+        pinnedBytes ??= bytes;
+        context.afterReadPage();
+        const nextAfterVersion = page.historyPage.nextAfterVersion;
+        yield result;
+        // A page consumer may await verification or storage while its session ends.
+        if (context.cancelled()) {
+            yield context.failure();
+            return;
+        }
+        if (nextAfterVersion === null)
+            return;
+        afterVersion = nextAfterVersion;
+    }
+}
+/** Full-bundle adapter for consumers that have not adopted durable staging. */
+export async function collectPrincipalPolicyPages(runtime, principalType, principalId, options) {
+    let current;
+    const previousStates = [];
+    for await (const result of readPrincipalPolicyPages(runtime, principalType, principalId, options)) {
+        if (!result.ok)
+            return null;
+        current ??= currentArtifacts(result.data);
+        previousStates.push(...result.data.previousStates);
+    }
+    return current ? { ...current, previousStates } : null;
+}
+function pageFailure(runtime, path, options, message, status) {
+    return runtime.responseRequest.reportFailure({
+        kind: "shape",
+        message,
+        method: "GET",
+        options,
+        path,
+        status,
+        statusText: "",
+    });
+}
+//# sourceMappingURL=principalPolicyPages.js.map

package/internal/api-client/principalPolicyPages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyPages.js","sourceRoot":"","sources":["principalPolicyPages.ts"],"names":[],"mappings":"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","sourcesContent":["import { serializeKeyingCanonicalJson } from \"@tearleads/crypto\";\nimport { getPrincipalPolicyOperation } from \"@tearleads/validators/operation\";\nimport type {\n  PrincipalPolicyBundleResponse,\n  PrincipalPolicyPageResponse,\n} from \"@tearleads/validators/response\";\nimport type { ApiRequestRuntime } from \"./apiRequestRuntime\";\nimport { principalHistoryRequest } from \"./principalHistoryRequest\";\nimport { PrincipalHistoryRequestContext } from \"./principalHistoryRequestContext\";\nimport { getPrincipalPolicy } from \"./routes/principals/policy\";\nimport type { RequestResult, RequestResultOptions } from \"./types\";\n\nexport type PrincipalPolicyPageCurrent = Omit<\n  PrincipalPolicyBundleResponse,\n  \"previousStates\"\n>;\n\n/** A transport position. Only the caller can authenticate the saved prefix. */\nexport interface PrincipalPolicyPageResume {\n  readonly current: PrincipalPolicyPageCurrent;\n  readonly afterVersion: number;\n}\n\nexport interface PrincipalPolicyPageReadOptions extends RequestResultOptions {\n  /** Select an exact signed head even before its first page has been read. */\n  readonly stateHash?: string | undefined;\n  /** Transport offset for a caller-authenticated prefix; requires stateHash. */\n  readonly afterVersion?: number | undefined;\n  readonly resume?: PrincipalPolicyPageResume | undefined;\n}\n\nfunction currentArtifacts(page: PrincipalPolicyPageResponse) {\n  return {\n    currentState: page.currentState,\n    currentPayload: page.currentPayload,\n    currentProjection: page.currentProjection,\n    currentGrants: page.currentGrants,\n    currentMemberEnvelopes: page.currentMemberEnvelopes,\n  };\n}\n\nfunction validResume(\n  principalType: \"group\" | \"organization\",\n  principalId: string,\n  resume: PrincipalPolicyPageResume,\n  stateHash: string | undefined,\n): boolean {\n  const state = resume.current.currentState;\n  return (\n    Number.isSafeInteger(resume.afterVersion) &&\n    resume.afterVersion >= 0 &&\n    resume.afterVersion < state.version &&\n    state.principalType === principalType &&\n    state.principalId === principalId &&\n    (stateHash === undefined || state.stateHash === stateHash)\n  );\n}\n\nfunction readResume(input: PrincipalPolicyPageResume | undefined) {\n  if (input === undefined) return undefined;\n  try {\n    const page = {\n      ...input.current,\n      previousStates: [],\n      historyPage: { afterVersion: input.afterVersion, nextAfterVersion: null },\n    };\n    if (!getPrincipalPolicy.isResponse(page)) return undefined;\n    const current = structuredClone(currentArtifacts(page));\n    return {\n      current,\n      afterVersion: page.historyPage.afterVersion,\n      bytes: serializeKeyingCanonicalJson(current),\n    };\n  } catch {\n    return undefined;\n  }\n}\n\nfunction validPage(\n  page: PrincipalPolicyPageResponse,\n  expected: {\n    principalType: \"group\" | \"organization\";\n    principalId: string;\n    stateHash: string | undefined;\n    pinnedBytes: string | undefined;\n    bytes: string;\n    afterVersion: number;\n  },\n): boolean {\n  const { afterVersion } = expected;\n  const lastVersion = afterVersion + page.previousStates.length;\n  return (\n    page.currentState.principalType === expected.principalType &&\n    page.currentState.principalId === expected.principalId &&\n    (expected.stateHash === undefined ||\n      page.currentState.stateHash === expected.stateHash) &&\n    (expected.pinnedBytes === undefined ||\n      expected.bytes === expected.pinnedBytes) &&\n    page.historyPage.afterVersion === afterVersion &&\n    lastVersion < page.currentState.version &&\n    page.previousStates.every(\n      ({ state }, index) =>\n        state.version === afterVersion + index + 1 &&\n        state.principalId === expected.principalId &&\n        state.principalType === expected.principalType,\n    ) &&\n    (page.historyPage.nextAfterVersion === null\n      ? lastVersion === page.currentState.version - 1\n      : lastVersion > afterVersion &&\n        lastVersion < page.currentState.version - 1 &&\n        page.historyPage.nextAfterVersion === lastVersion)\n  );\n}\n\nfunction preparePrincipalPolicyRead(\n  runtime: ApiRequestRuntime,\n  principalType: \"group\" | \"organization\",\n  principalId: string,\n  options: PrincipalPolicyPageReadOptions,\n) {\n  const query =\n    options.stateHash === undefined\n      ? {}\n      : {\n          afterVersion: options.afterVersion ?? 0,\n          stateHash: options.stateHash,\n        };\n  const basePath = getPrincipalPolicy.path(principalType, principalId);\n  const failure = (message: string) => ({\n    ok: false as const,\n    failure: pageFailure(runtime, basePath, options, message, null),\n  });\n  if (\n    options.afterVersion !== undefined &&\n    (options.stateHash === undefined ||\n      options.resume !== undefined ||\n      !Number.isSafeInteger(options.afterVersion))\n  )\n    return failure(\"Initial principal history cursor requires one exact head\");\n  if (!getPrincipalPolicyOperation.query.safeParse(query).success)\n    return failure(\"Invalid requested principal history head\");\n  const resume = readResume(options.resume);\n  if (\n    options.resume !== undefined &&\n    (!resume ||\n      !validResume(principalType, principalId, resume, options.stateHash))\n  )\n    return failure(\"Invalid saved principal history position\");\n  return {\n    ok: true as const,\n    firstPath: getPrincipalPolicy.path(principalType, principalId, query),\n    afterVersion: options.afterVersion ?? 0,\n    resume,\n  };\n}\n\n/** Pull one page at a time; the caller owns verification and durable admission. */\nexport async function* readPrincipalPolicyPages(\n  runtime: ApiRequestRuntime,\n  principalType: \"group\" | \"organization\",\n  principalId: string,\n  options: PrincipalPolicyPageReadOptions,\n): AsyncGenerator<RequestResult<PrincipalPolicyPageResponse>, void> {\n  const position = preparePrincipalPolicyRead(\n    runtime,\n    principalType,\n    principalId,\n    options,\n  );\n  if (!position.ok) {\n    yield position.failure;\n    return;\n  }\n  const { firstPath, resume } = position;\n  const context = new PrincipalHistoryRequestContext(\n    runtime,\n    \"GET\",\n    firstPath,\n    options,\n  );\n  let pinned = resume?.current;\n  let pinnedBytes = resume?.bytes;\n  let afterVersion = resume?.afterVersion ?? position.afterVersion;\n  while (true) {\n    const path = pinned\n      ? getPrincipalPolicy.path(principalType, principalId, {\n          afterVersion,\n          stateHash: pinned.currentState.stateHash,\n        })\n      : firstPath;\n    const result = await principalHistoryRequest(runtime, {\n      path,\n      validator: getPrincipalPolicy.isResponse,\n      method: \"GET\",\n      operation: getPrincipalPolicyOperation,\n      options,\n      context,\n    });\n    if (!result.ok) {\n      yield result;\n      return;\n    }\n    const page = result.data;\n    const artifacts = currentArtifacts(page);\n    const bytes = serializeKeyingCanonicalJson(artifacts);\n    const valid = validPage(page, {\n      principalType,\n      principalId,\n      stateHash: options.stateHash,\n      pinnedBytes,\n      bytes,\n      afterVersion,\n    });\n    if (!valid) {\n      yield pageFailure(\n        runtime,\n        path,\n        options,\n        \"Principal history page changed its head, order, or cursor\",\n        200,\n      );\n      return;\n    }\n    pinned ??= structuredClone(artifacts);\n    pinnedBytes ??= bytes;\n    context.afterReadPage();\n    const nextAfterVersion = page.historyPage.nextAfterVersion;\n    yield result;\n    // A page consumer may await verification or storage while its session ends.\n    if (context.cancelled()) {\n      yield context.failure();\n      return;\n    }\n    if (nextAfterVersion === null) return;\n    afterVersion = nextAfterVersion;\n  }\n}\n\n/** Full-bundle adapter for consumers that have not adopted durable staging. */\nexport async function collectPrincipalPolicyPages(\n  runtime: ApiRequestRuntime,\n  principalType: \"group\" | \"organization\",\n  principalId: string,\n  options: RequestResultOptions,\n): Promise<PrincipalPolicyBundleResponse | null> {\n  let current: PrincipalPolicyPageCurrent | undefined;\n  const previousStates: PrincipalPolicyBundleResponse[\"previousStates\"] = [];\n  for await (const result of readPrincipalPolicyPages(\n    runtime,\n    principalType,\n    principalId,\n    options,\n  )) {\n    if (!result.ok) return null;\n    current ??= currentArtifacts(result.data);\n    previousStates.push(...result.data.previousStates);\n  }\n  return current ? { ...current, previousStates } : null;\n}\n\nfunction pageFailure(\n  runtime: ApiRequestRuntime,\n  path: string,\n  options: RequestResultOptions,\n  message: string,\n  status: number | null,\n) {\n  return runtime.responseRequest.reportFailure({\n    kind: \"shape\",\n    message,\n    method: \"GET\",\n    options,\n    path,\n    status,\n    statusText: \"\",\n  });\n}\n"]}

package/internal/api-client/principalPolicyRequests.js

@@ -0,0 +1,68 @@
+import { commitOrganizationGroupPolicyOperation, putPrincipalPolicyOperation, } from "../validators/operation/index.js";
+import { principalHistoryRequest } from "./principalHistoryRequest.js";
+import { collectPrincipalPolicyPages, readPrincipalPolicyPages, } from "./principalPolicyPages.js";
+import { dedupedRequest } from "./requestInternals.js";
+import { commitOrganizationGroupPolicy, putPrincipalPolicy, } from "./routes/principals/policy.js";
+export class PrincipalPolicyRequests {
+    runtime;
+    cache;
+    clearWriterProjectionCaches;
+    constructor(runtime, cache, clearWriterProjectionCaches) {
+        this.runtime = runtime;
+        this.cache = cache;
+        this.clearWriterProjectionCaches = clearWriterProjectionCaches;
+    }
+    pages(principalType, principalId, options = {}) {
+        return readPrincipalPolicyPages(this.runtime, principalType, principalId, options);
+    }
+    get(principalType, principalId, options = {}) {
+        const request = () => collectPrincipalPolicyPages(this.runtime, principalType, principalId, options);
+        const key = JSON.stringify([principalType, principalId]);
+        // Cancellation, reporting and renewal preferences belong to their caller.
+        return Object.keys(options).length > 0
+            ? request()
+            : dedupedRequest(this.cache, key, request);
+    }
+    put(principalType, principalId, input, options = {}) {
+        const key = JSON.stringify([principalType, principalId]);
+        this.cache.delete(key);
+        return principalHistoryRequest(this.runtime, {
+            path: putPrincipalPolicy.path(principalType, principalId),
+            validator: putPrincipalPolicy.isResponse,
+            method: putPrincipalPolicy.method,
+            body: JSON.stringify(input),
+            options: {
+                expectedPaymentRequiredOrganizationId: principalId,
+                ...options,
+            },
+            operation: putPrincipalPolicyOperation,
+        })
+            .then((result) => (result.ok ? result.data : null))
+            .finally(() => this.cache.delete(key));
+    }
+    async commitResult(organizationId, groupId, input, options = {}) {
+        const groupKey = JSON.stringify(["group", groupId]);
+        const organizationKey = JSON.stringify(["organization", organizationId]);
+        this.cache.delete(groupKey);
+        this.cache.delete(organizationKey);
+        try {
+            return await principalHistoryRequest(this.runtime, {
+                path: commitOrganizationGroupPolicy.path(organizationId, groupId),
+                validator: commitOrganizationGroupPolicy.isResponse,
+                method: commitOrganizationGroupPolicy.method,
+                body: JSON.stringify(input),
+                options: {
+                    expectedPaymentRequiredOrganizationId: organizationId,
+                    ...options,
+                },
+                operation: commitOrganizationGroupPolicyOperation,
+            });
+        }
+        finally {
+            this.cache.delete(groupKey);
+            this.cache.delete(organizationKey);
+            this.clearWriterProjectionCaches();
+        }
+    }
+}
+//# sourceMappingURL=principalPolicyRequests.js.map

package/internal/api-client/principalPolicyRequests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalPolicyRequests.js","sourceRoot":"","sources":["principalPolicyRequests.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sCAAsC,EACtC,2BAA2B,GAC5B,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EACL,2BAA2B,EAE3B,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAGpC,MAAM,OAAO,uBAAuB;IAEf;IACA;IAGA;IALnB,YACmB,OAA0B,EAC1B,KAEhB,EACgB,2BAAuC;QAJvC,YAAO,GAAP,OAAO,CAAmB;QAC1B,UAAK,GAAL,KAAK,CAErB;QACgB,gCAA2B,GAA3B,2BAA2B,CAAY;IACvD,CAAC;IAEJ,KAAK,CACH,aAAuC,EACvC,WAAmB,EACnB,UAA0C,EAAE;QAE5C,OAAO,wBAAwB,CAC7B,IAAI,CAAC,OAAO,EACZ,aAAa,EACb,WAAW,EACX,OAAO,CACR,CAAC;IACJ,CAAC;IAED,GAAG,CACD,aAAuC,EACvC,WAAmB,EACnB,UAAgC,EAAE;QAElC,MAAM,OAAO,GAAG,GAAG,EAAE,CACnB,2BAA2B,CACzB,IAAI,CAAC,OAAO,EACZ,aAAa,EACb,WAAW,EACX,OAAO,CACR,CAAC;QACJ,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;QACzD,0EAA0E;QAC1E,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;YACpC,CAAC,CAAC,OAAO,EAAE;YACX,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,GAAG,CACD,aAA6B,EAC7B,WAAmB,EACnB,KAAyC,EACzC,UAAgC,EAAE;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;QACzD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE;YAC3C,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC;YACzD,SAAS,EAAE,kBAAkB,CAAC,UAAU;YACxC,MAAM,EAAE,kBAAkB,CAAC,MAAM;YACjC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAC3B,OAAO,EAAE;gBACP,qCAAqC,EAAE,WAAW;gBAClD,GAAG,OAAO;aACX;YACD,SAAS,EAAE,2BAA2B;SACvC,CAAC;aACC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;aAClD,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,cAAsB,EACtB,OAAe,EACf,KAA2C,EAC3C,UAAgC,EAAE;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACpD,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,OAAO,MAAM,uBAAuB,CAAC,IAAI,CAAC,OAAO,EAAE;gBACjD,IAAI,EAAE,6BAA6B,CAAC,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC;gBACjE,SAAS,EAAE,6BAA6B,CAAC,UAAU;gBACnD,MAAM,EAAE,6BAA6B,CAAC,MAAM;gBAC5C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBAC3B,OAAO,EAAE;oBACP,qCAAqC,EAAE,cAAc;oBACrD,GAAG,OAAO;iBACX;gBACD,SAAS,EAAE,sCAAsC;aAClD,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;YACnC,IAAI,CAAC,2BAA2B,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;CACF","sourcesContent":["import {\n  commitOrganizationGroupPolicyOperation,\n  putPrincipalPolicyOperation,\n} from \"@tearleads/validators/operation\";\nimport type {\n  CommitOrganizationGroupPolicyRequest,\n  OrganizationPrincipalPolicyRequest,\n} from \"@tearleads/validators/request\";\nimport type { PrincipalPolicyBundleResponse } from \"@tearleads/validators/response\";\nimport type { BoundedCache } from \"./ApiCache\";\nimport type { ApiRequestRuntime } from \"./apiRequestRuntime\";\nimport { principalHistoryRequest } from \"./principalHistoryRequest\";\nimport {\n  collectPrincipalPolicyPages,\n  type PrincipalPolicyPageReadOptions,\n  readPrincipalPolicyPages,\n} from \"./principalPolicyPages\";\nimport { dedupedRequest } from \"./requestInternals\";\nimport {\n  commitOrganizationGroupPolicy,\n  putPrincipalPolicy,\n} from \"./routes/principals/policy\";\nimport type { RequestResultOptions } from \"./types\";\n\nexport class PrincipalPolicyRequests {\n  constructor(\n    private readonly runtime: ApiRequestRuntime,\n    private readonly cache: BoundedCache<\n      Promise<PrincipalPolicyBundleResponse | null>\n    >,\n    private readonly clearWriterProjectionCaches: () => void,\n  ) {}\n\n  pages(\n    principalType: \"group\" | \"organization\",\n    principalId: string,\n    options: PrincipalPolicyPageReadOptions = {},\n  ) {\n    return readPrincipalPolicyPages(\n      this.runtime,\n      principalType,\n      principalId,\n      options,\n    );\n  }\n\n  get(\n    principalType: \"group\" | \"organization\",\n    principalId: string,\n    options: RequestResultOptions = {},\n  ) {\n    const request = () =>\n      collectPrincipalPolicyPages(\n        this.runtime,\n        principalType,\n        principalId,\n        options,\n      );\n    const key = JSON.stringify([principalType, principalId]);\n    // Cancellation, reporting and renewal preferences belong to their caller.\n    return Object.keys(options).length > 0\n      ? request()\n      : dedupedRequest(this.cache, key, request);\n  }\n\n  put(\n    principalType: \"organization\",\n    principalId: string,\n    input: OrganizationPrincipalPolicyRequest,\n    options: RequestResultOptions = {},\n  ) {\n    const key = JSON.stringify([principalType, principalId]);\n    this.cache.delete(key);\n    return principalHistoryRequest(this.runtime, {\n      path: putPrincipalPolicy.path(principalType, principalId),\n      validator: putPrincipalPolicy.isResponse,\n      method: putPrincipalPolicy.method,\n      body: JSON.stringify(input),\n      options: {\n        expectedPaymentRequiredOrganizationId: principalId,\n        ...options,\n      },\n      operation: putPrincipalPolicyOperation,\n    })\n      .then((result) => (result.ok ? result.data : null))\n      .finally(() => this.cache.delete(key));\n  }\n\n  async commitResult(\n    organizationId: string,\n    groupId: string,\n    input: CommitOrganizationGroupPolicyRequest,\n    options: RequestResultOptions = {},\n  ) {\n    const groupKey = JSON.stringify([\"group\", groupId]);\n    const organizationKey = JSON.stringify([\"organization\", organizationId]);\n    this.cache.delete(groupKey);\n    this.cache.delete(organizationKey);\n    try {\n      return await principalHistoryRequest(this.runtime, {\n        path: commitOrganizationGroupPolicy.path(organizationId, groupId),\n        validator: commitOrganizationGroupPolicy.isResponse,\n        method: commitOrganizationGroupPolicy.method,\n        body: JSON.stringify(input),\n        options: {\n          expectedPaymentRequiredOrganizationId: organizationId,\n          ...options,\n        },\n        operation: commitOrganizationGroupPolicyOperation,\n      });\n    } finally {\n      this.cache.delete(groupKey);\n      this.cache.delete(organizationKey);\n      this.clearWriterProjectionCaches();\n    }\n  }\n}\n"]}

package/internal/api-client/projectionHistoryTransport.js

@@ -0,0 +1,107 @@
+import { captureProjectionHistory, restoreProjectionHistory, } from "../crypto/index.js";
+import { isContainerWriterProjectionResponse, isDocumentWriterProjectionResponse, } from "../validators/response/index.js";
+import { PROJECTION_HISTORY_HINT_CHARACTERS, ProjectionHistoryPrefixesSchema, } from "../validators/util/index.js";
+import { registerProjectionHistoryAdmission } from "./verifiedProjectionHistory.js";
+const MAX_HISTORY_CHARACTERS = 16_000_000;
+const MAX_PROJECTIONS = 16;
+/** Session-scoped evidence cache, independent of the short-lived current-head cache. */
+export class ProjectionHistoryTransport {
+    retained = new Map();
+    characters = 0;
+    generation = 0;
+    clear() {
+        this.generation += 1;
+        this.characters = 0;
+        this.retained.clear();
+    }
+    remember(path, entries) {
+        const characters = JSON.stringify(entries).length;
+        if (characters > MAX_HISTORY_CHARACTERS)
+            return;
+        this.characters -= this.retained.get(path)?.characters ?? 0;
+        this.retained.delete(path);
+        this.retained.set(path, { entries, characters });
+        this.characters += characters;
+        while (this.characters > MAX_HISTORY_CHARACTERS ||
+            this.retained.size > MAX_PROJECTIONS) {
+            const oldest = this.retained.entries().next().value;
+            if (!oldest)
+                break;
+            this.characters -= oldest[1].characters;
+            this.retained.delete(oldest[0]);
+        }
+    }
+    prepare(path, validator, method, options, operation) {
+        if (method !== "GET" ||
+            ![
+                "containers.writerProjection.get",
+                "documents.writerProjection.get",
+            ].includes(operation.id))
+            return { options, validator };
+        const generation = this.generation;
+        const mayRetain = options?.headers === undefined;
+        const candidates = mayRetain
+            ? (this.retained.get(path)?.entries ?? [])
+            : [];
+        const requested = [];
+        for (const entry of candidates) {
+            const prefixes = [...requested, entry].map((item) => item.prefix);
+            if (!ProjectionHistoryPrefixesSchema.safeParse(prefixes).success)
+                continue;
+            // Bound negotiation headers; deep paths merely omit fewer hints.
+            if (encodeURIComponent(JSON.stringify(prefixes)).length <=
+                PROJECTION_HISTORY_HINT_CHARACTERS)
+                requested.push(entry);
+        }
+        const hint = JSON.stringify(requested.map((entry) => entry.prefix));
+        const requestOptions = requested.length
+            ? {
+                ...options,
+                headers: { "x-projection-history": encodeURIComponent(hint) },
+            }
+            : options;
+        return {
+            options: requestOptions,
+            validator: (value) => {
+                if (!validator(value))
+                    return false;
+                let projection;
+                if (isContainerWriterProjectionResponse(value) ||
+                    isDocumentWriterProjectionResponse(value))
+                    projection = value;
+                else
+                    return false;
+                // A transparent token-refresh retry still holds its requested bytes.
+                // Restore them here; the admission guard below preserves auth clearing.
+                if (!restoreProjectionHistory(projection, requested) ||
+                    !validator(value))
+                    return false;
+                const captured = JSON.stringify(captureProjectionHistory(projection).map((entry) => entry.prefix));
+                registerProjectionHistoryAdmission(projection, () => {
+                    if (!mayRetain || generation !== this.generation)
+                        return;
+                    // A consumer may mutate a decoded object. Never retain bytes other
+                    // than the exact evidence that passed through the verification call.
+                    const observed = captureProjectionHistory(projection);
+                    if (JSON.stringify(observed.map((entry) => entry.prefix)) !== captured)
+                        return;
+                    this.remember(path, observed);
+                });
+                return true;
+            },
+        };
+    }
+    wrapRequest(request) {
+        return (path, validator, method, body, options, operation) => {
+            const prepared = this.prepare(path, validator, method, options, operation);
+            return request(path, prepared.validator, method, body, prepared.options, operation);
+        };
+    }
+    wrapRequestResult(request) {
+        return (path, validator, method, body, options, operation) => {
+            const prepared = this.prepare(path, validator, method, options, operation);
+            return request(path, prepared.validator, method, body, prepared.options, operation);
+        };
+    }
+}
+//# sourceMappingURL=projectionHistoryTransport.js.map