@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/cjs/data/error.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataError = exports.ACCESS_REASONS = void 0;
+exports.appStatus = appStatus;
+exports.toDataError = toDataError;
+/**
+ * Stable `data.reason` codes UNS adds when it refuses App data access; the
+ * top-level code stays FORBIDDEN / NOT_FOUND. Only whole-request errors carry
+ * them, never per-item results of a batch or transaction.
+ */
+exports.ACCESS_REASONS = {
+    /** 403: the collection exists, but this App's grant does not cover it or the operation. */
+    notGranted: 'COLLECTION_NOT_GRANTED',
+    /** 403 or 404: the collection is gone (hard-deleted or archived). */
+    notFound: 'COLLECTION_NOT_FOUND',
+    /** 403: the grant covers the operation, the App key lacks `data.missingPermission`. */
+    permissionMissing: 'APP_PERMISSION_MISSING',
+};
+class DataError extends Error {
+    /** HTTP status the App should answer with (see `appStatus`). */
+    status;
+    /** UNS error code, e.g. `DUPLICATE_KEY`, or a data-layer code. */
+    code;
+    /** Stable `data.reason` code, e.g. `COLLECTION_NOT_FOUND` (see ACCESS_REASONS). */
+    reason;
+    /** HTTP status UNS answered with; 0 when no response arrived. */
+    upstreamStatus;
+    requestId;
+    /**
+     * How far the failed request got: `notStarted` / `rolledBack` changed
+     * nothing, `committed` took effect, `unknown` (writes only) may have.
+     * Data-layer refusals raised before sending are `notStarted`.
+     */
+    execution;
+    /** Whether the same call may be repeated later, and after how long. The data layer already retried it. */
+    retry;
+    /** `execution === "unknown"`: a write may have landed. Read back before writing again. */
+    outcomeUnknown;
+    /** Requests sent for this call, retries included; 0 when nothing was sent. */
+    attempts;
+    /**
+     * The idempotency key the write was sent with (generated unless the caller
+     * gave one). After `outcomeUnknown`, sending the same write with this key
+     * again cannot apply it twice.
+     */
+    idempotencyKey;
+    /** The `data` object of the UNS error envelope, or data-layer details. */
+    details;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = 'DataError';
+        this.status = init.status;
+        this.code = init.code;
+        this.reason = init.reason;
+        this.upstreamStatus = init.upstreamStatus ?? 0;
+        this.requestId = init.requestId;
+        this.execution = init.execution ?? 'notStarted';
+        this.retry = init.retry ?? { safe: false };
+        this.outcomeUnknown = this.execution === 'unknown';
+        this.attempts = init.attempts ?? 0;
+        this.idempotencyKey = init.idempotencyKey;
+        this.details = init.details ?? {};
+    }
+}
+exports.DataError = DataError;
+/** Platform states the App's caller cannot fix: they answer 503 whatever UNS answered. */
+const PLATFORM_CODES = new Set(['APP_NOT_READY', 'DEPENDENCY_UNAVAILABLE', 'CREDENTIAL_CHANGED', 'OUTCOME_UNKNOWN', 'TEMPORARILY_UNAVAILABLE']);
+/**
+ * Maps an upstream UNS status and code to the status the App answers its own
+ * caller with. Credential failures are the platform's problem, not the user's
+ * session, so a 401 from UNS becomes 502 instead of looking like a logout;
+ * platform states (App not ready yet, a dependency down, the App key changed
+ * mid-request) become 503 instead of looking like a denied action or a conflict.
+ */
+function appStatus(upstream, code = '') {
+    if (upstream === 401)
+        return 502;
+    if (PLATFORM_CODES.has(code))
+        return 503;
+    if (upstream === 400 || upstream === 403 || upstream === 404 || upstream === 409 || upstream === 413 || upstream === 422 || upstream === 429) {
+        return upstream;
+    }
+    if (upstream === 502 || upstream === 503 || upstream === 504)
+        return 503;
+    if (upstream >= 500)
+        return 502;
+    return upstream >= 400 ? 400 : 502;
+}
+const CODE_HINTS = {
+    UPSERT_REQUIRES_UNIQUE_INDEX: 'An upsert filter must contain `_id` or every field of a unique index that is already ready; a newly declared unique index may still be building.',
+    DUPLICATE_KEY: 'A unique index already holds this value. (From restore: an active record took the value meanwhile; nothing was restored.)',
+    VERSION_CONFLICT: 'The record changed since it was read; reload it and retry with the new revision.',
+    APP_GRANT_REVOKED: "A workspace admin revoked this App's access to the collection; it is not re-granted automatically. Ask the admin to restore the grant.",
+    INDEX_QUOTA_EXCEEDED: 'The workspace index quota (200, counting every index that physically exists) is exhausted. Remove unused indexes through the tier0 MCP.',
+    COLLECTION_TOO_LARGE: 'archive / restore handle at most 2000 records; stop using a large collection in code instead of archiving it.',
+    OVERLOADED: "This workspace's data requests are over their concurrency share; the data layer already waited and retried. Batch page reads with data.queryBatch and avoid per-record loops.",
+    APP_NOT_READY: 'The platform is still preparing this App (e.g. right after an import); retry shortly.',
+    QUERY_TIMEOUT: 'Narrow the query: add an indexed condition, a smaller limit or maxCount.',
+    OUTCOME_UNKNOWN: 'The write may have committed; read the record back before writing again.',
+};
+/** `APP_QUOTA_EXCEEDED` per `data.resource`; each per-App limit is 64. */
+const QUOTA_HINTS = {
+    collections: 'This App owns 64 active collections. Archive unused ones through the tier0 MCP.',
+    indexes: "This App's collections hold 64 indexes. Drop unused indexes from the declarations, then apply that with schema:replace through the tier0 MCP.",
+    archivedCollections: 'This App keeps 64 archived collections. Restore one, or ask a workspace admin to clean up archived collections.',
+};
+/** SDK transport failures: no UNS answer to map, so the data layer names them. */
+const TRANSPORT_FAILURES = {
+    UNS_V2_TRANSPORT_TIMEOUT: { code: 'DATA_TIMEOUT', status: 503, message: 'UNS did not answer in time' },
+    UNS_V2_TRANSPORT_ERROR: { code: 'DATA_UNREACHABLE', status: 503, message: 'Cannot reach the Tier0 data service' },
+    // The business request was aborted while the call was in flight (499: client closed request).
+    UNS_V2_TRANSPORT_ABORTED: { code: 'DATA_ABORTED', status: 499, message: 'The data call was aborted' },
+    UNS_V2_PROTOCOL_ERROR: { code: 'DATA_BAD_RESPONSE', status: 502, message: 'UNS answered with an invalid response' },
+};
+function codeHint(code, details) {
+    if (code === 'APP_QUOTA_EXCEEDED') {
+        const resource = typeof details.resource === 'string' ? details.resource : '';
+        return QUOTA_HINTS[resource] ?? 'This App reached a collection/index quota. Remove unused collections or indexes through the tier0 MCP.';
+    }
+    return CODE_HINTS[code];
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Translates a failed UNS call of the SDK client after `attempts` requests, sent with `idempotencyKey`. */
+function toDataError(error, attempts = 1, idempotencyKey) {
+    const common = {
+        upstreamStatus: error.status,
+        requestId: error.requestId,
+        execution: error.execution,
+        retry: error.retry,
+        attempts,
+        idempotencyKey,
+        cause: error,
+    };
+    const unknown = error.outcomeUnknown ? '; the write outcome is unknown' : '';
+    // An ingress or load balancer answers 502/503/504 without the UNS envelope during
+    // rolling releases and pod restarts, like any unavailable upstream. UNS v2 routes
+    // answer every other error with the envelope (401/403/429 included), so other
+    // unenveloped responses stay DATA_BAD_RESPONSE.
+    if (error.code === 'UNS_V2_PROTOCOL_ERROR' && (error.status === 502 || error.status === 503 || error.status === 504)) {
+        return new DataError({
+            ...common,
+            message: `The Tier0 data gateway answered ${error.operation} with HTTP ${error.status}${unknown}.`,
+            status: 503,
+            code: `HTTP_${error.status}`,
+        });
+    }
+    const transport = TRANSPORT_FAILURES[error.code];
+    if (transport) {
+        return new DataError({ ...common, message: `${transport.message} (${error.operation})${unknown}.`, status: transport.status, code: transport.code });
+    }
+    const httpStatus = error.status ?? 0;
+    const data = isObject(error.data) ? error.data : {};
+    // Only `data.reason` is a code; `error.reason` repeats the message text.
+    const reason = typeof data.reason === 'string' ? data.reason : undefined;
+    const code = error.code;
+    const msg = error.message;
+    const hint = codeHint(code, data) ?? error.repair;
+    let message = `${msg} (${code})`;
+    if (reason === exports.ACCESS_REASONS.permissionMissing) {
+        message =
+            data.missingPermission === 'uns.delete'
+                ? `Deleting records requires the App key to hold uns.delete, and this App's key does not (${code}). ` +
+                    'Model removal as a status change such as `archived`, or ask a workspace admin to grant uns.delete.'
+                : `The App key lacks ${typeof data.missingPermission === 'string' ? data.missingPermission : 'a permission'} for this operation (${code}); ask a workspace admin.`;
+    }
+    else if (reason === exports.ACCESS_REASONS.notGranted) {
+        message = `${message} This App's grant does not cover the collection or operation; ask a workspace admin to restore the grant.`;
+    }
+    else if (reason === exports.ACCESS_REASONS.notFound) {
+        message = `${message} The collection was archived or deleted; the data layer ensures the declared collections again.`;
+    }
+    else if (httpStatus === 401) {
+        message = `Tier0 rejected the App credential for ${error.operation} (${code}). The platform injects TIER0_API_KEY; do not replace it.`;
+    }
+    else if (hint) {
+        message = `${message} ${hint}`;
+    }
+    return new DataError({ ...common, message, status: appStatus(httpStatus, code), code, reason, upstreamStatus: httpStatus, details: data });
+}
+//# sourceMappingURL=error.js.map

package/dist/cjs/data/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/data/error.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime failures of a data call, missing credentials included, are a\n * `DataError`. The SDK's UNS client does the HTTP exchange; its `UnsV2Error`\n * (kept as `cause`) is translated here, and the data layer raises its own codes\n * (BATCH_LIMIT_EXCEEDED, WRITE_ERRORS, ...). `status` is the HTTP status the App\n * should answer its own caller with. Writes that fail validation throw\n * `ZodError`; programming or platform errors, such as invalid client options or\n * a malformed data subject from the gateway, throw `TypeError`.\n */\nimport type { UnsV2Error, UnsV2Execution, UnsV2Retry } from '../uns-v2/client.js';\n\n/**\n * Stable `data.reason` codes UNS adds when it refuses App data access; the\n * top-level code stays FORBIDDEN / NOT_FOUND. Only whole-request errors carry\n * them, never per-item results of a batch or transaction.\n */\nexport const ACCESS_REASONS = {\n  /** 403: the collection exists, but this App's grant does not cover it or the operation. */\n  notGranted: 'COLLECTION_NOT_GRANTED',\n  /** 403 or 404: the collection is gone (hard-deleted or archived). */\n  notFound: 'COLLECTION_NOT_FOUND',\n  /** 403: the grant covers the operation, the App key lacks `data.missingPermission`. */\n  permissionMissing: 'APP_PERMISSION_MISSING',\n} as const;\n\nexport class DataError extends Error {\n  /** HTTP status the App should answer with (see `appStatus`). */\n  readonly status: number;\n  /** UNS error code, e.g. `DUPLICATE_KEY`, or a data-layer code. */\n  readonly code: string;\n  /** Stable `data.reason` code, e.g. `COLLECTION_NOT_FOUND` (see ACCESS_REASONS). */\n  readonly reason?: string;\n  /** HTTP status UNS answered with; 0 when no response arrived. */\n  readonly upstreamStatus: number;\n  readonly requestId?: string;\n  /**\n   * How far the failed request got: `notStarted` / `rolledBack` changed\n   * nothing, `committed` took effect, `unknown` (writes only) may have.\n   * Data-layer refusals raised before sending are `notStarted`.\n   */\n  readonly execution: UnsV2Execution;\n  /** Whether the same call may be repeated later, and after how long. The data layer already retried it. */\n  readonly retry: UnsV2Retry;\n  /** `execution === \"unknown\"`: a write may have landed. Read back before writing again. */\n  readonly outcomeUnknown: boolean;\n  /** Requests sent for this call, retries included; 0 when nothing was sent. */\n  readonly attempts: number;\n  /**\n   * The idempotency key the write was sent with (generated unless the caller\n   * gave one). After `outcomeUnknown`, sending the same write with this key\n   * again cannot apply it twice.\n   */\n  readonly idempotencyKey?: string;\n  /** The `data` object of the UNS error envelope, or data-layer details. */\n  readonly details: Record<string, unknown>;\n\n  constructor(init: {\n    message: string;\n    status: number;\n    code: string;\n    reason?: string;\n    upstreamStatus?: number;\n    requestId?: string;\n    execution?: UnsV2Execution;\n    retry?: UnsV2Retry;\n    attempts?: number;\n    idempotencyKey?: string;\n    details?: Record<string, unknown>;\n    cause?: unknown;\n  }) {\n    super(init.message, init.cause === undefined ? undefined : { cause: init.cause });\n    this.name = 'DataError';\n    this.status = init.status;\n    this.code = init.code;\n    this.reason = init.reason;\n    this.upstreamStatus = init.upstreamStatus ?? 0;\n    this.requestId = init.requestId;\n    this.execution = init.execution ?? 'notStarted';\n    this.retry = init.retry ?? { safe: false };\n    this.outcomeUnknown = this.execution === 'unknown';\n    this.attempts = init.attempts ?? 0;\n    this.idempotencyKey = init.idempotencyKey;\n    this.details = init.details ?? {};\n  }\n}\n\n/** Platform states the App's caller cannot fix: they answer 503 whatever UNS answered. */\nconst PLATFORM_CODES = new Set(['APP_NOT_READY', 'DEPENDENCY_UNAVAILABLE', 'CREDENTIAL_CHANGED', 'OUTCOME_UNKNOWN', 'TEMPORARILY_UNAVAILABLE']);\n\n/**\n * Maps an upstream UNS status and code to the status the App answers its own\n * caller with. Credential failures are the platform's problem, not the user's\n * session, so a 401 from UNS becomes 502 instead of looking like a logout;\n * platform states (App not ready yet, a dependency down, the App key changed\n * mid-request) become 503 instead of looking like a denied action or a conflict.\n */\nexport function appStatus(upstream: number, code = ''): number {\n  if (upstream === 401) return 502;\n  if (PLATFORM_CODES.has(code)) return 503;\n  if (upstream === 400 || upstream === 403 || upstream === 404 || upstream === 409 || upstream === 413 || upstream === 422 || upstream === 429) {\n    return upstream;\n  }\n  if (upstream === 502 || upstream === 503 || upstream === 504) return 503;\n  if (upstream >= 500) return 502;\n  return upstream >= 400 ? 400 : 502;\n}\n\nconst CODE_HINTS: Record<string, string> = {\n  UPSERT_REQUIRES_UNIQUE_INDEX:\n    'An upsert filter must contain `_id` or every field of a unique index that is already ready; a newly declared unique index may still be building.',\n  DUPLICATE_KEY:\n    'A unique index already holds this value. (From restore: an active record took the value meanwhile; nothing was restored.)',\n  VERSION_CONFLICT: 'The record changed since it was read; reload it and retry with the new revision.',\n  APP_GRANT_REVOKED:\n    \"A workspace admin revoked this App's access to the collection; it is not re-granted automatically. Ask the admin to restore the grant.\",\n  INDEX_QUOTA_EXCEEDED:\n    'The workspace index quota (200, counting every index that physically exists) is exhausted. Remove unused indexes through the tier0 MCP.',\n  COLLECTION_TOO_LARGE:\n    'archive / restore handle at most 2000 records; stop using a large collection in code instead of archiving it.',\n  OVERLOADED:\n    \"This workspace's data requests are over their concurrency share; the data layer already waited and retried. Batch page reads with data.queryBatch and avoid per-record loops.\",\n  APP_NOT_READY: 'The platform is still preparing this App (e.g. right after an import); retry shortly.',\n  QUERY_TIMEOUT: 'Narrow the query: add an indexed condition, a smaller limit or maxCount.',\n  OUTCOME_UNKNOWN: 'The write may have committed; read the record back before writing again.',\n};\n\n/** `APP_QUOTA_EXCEEDED` per `data.resource`; each per-App limit is 64. */\nconst QUOTA_HINTS: Record<string, string> = {\n  collections: 'This App owns 64 active collections. Archive unused ones through the tier0 MCP.',\n  indexes: \"This App's collections hold 64 indexes. Drop unused indexes from the declarations, then apply that with schema:replace through the tier0 MCP.\",\n  archivedCollections:\n    'This App keeps 64 archived collections. Restore one, or ask a workspace admin to clean up archived collections.',\n};\n\n/** SDK transport failures: no UNS answer to map, so the data layer names them. */\nconst TRANSPORT_FAILURES: Record<string, { code: string; status: number; message: string }> = {\n  UNS_V2_TRANSPORT_TIMEOUT: { code: 'DATA_TIMEOUT', status: 503, message: 'UNS did not answer in time' },\n  UNS_V2_TRANSPORT_ERROR: { code: 'DATA_UNREACHABLE', status: 503, message: 'Cannot reach the Tier0 data service' },\n  // The business request was aborted while the call was in flight (499: client closed request).\n  UNS_V2_TRANSPORT_ABORTED: { code: 'DATA_ABORTED', status: 499, message: 'The data call was aborted' },\n  UNS_V2_PROTOCOL_ERROR: { code: 'DATA_BAD_RESPONSE', status: 502, message: 'UNS answered with an invalid response' },\n};\n\nfunction codeHint(code: string, details: Record<string, unknown>): string | undefined {\n  if (code === 'APP_QUOTA_EXCEEDED') {\n    const resource = typeof details.resource === 'string' ? details.resource : '';\n    return QUOTA_HINTS[resource] ?? 'This App reached a collection/index quota. Remove unused collections or indexes through the tier0 MCP.';\n  }\n  return CODE_HINTS[code];\n}\n\nfunction isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** Translates a failed UNS call of the SDK client after `attempts` requests, sent with `idempotencyKey`. */\nexport function toDataError(error: UnsV2Error, attempts = 1, idempotencyKey?: string): DataError {\n  const common = {\n    upstreamStatus: error.status,\n    requestId: error.requestId,\n    execution: error.execution,\n    retry: error.retry,\n    attempts,\n    idempotencyKey,\n    cause: error,\n  };\n  const unknown = error.outcomeUnknown ? '; the write outcome is unknown' : '';\n  // An ingress or load balancer answers 502/503/504 without the UNS envelope during\n  // rolling releases and pod restarts, like any unavailable upstream. UNS v2 routes\n  // answer every other error with the envelope (401/403/429 included), so other\n  // unenveloped responses stay DATA_BAD_RESPONSE.\n  if (error.code === 'UNS_V2_PROTOCOL_ERROR' && (error.status === 502 || error.status === 503 || error.status === 504)) {\n    return new DataError({\n      ...common,\n      message: `The Tier0 data gateway answered ${error.operation} with HTTP ${error.status}${unknown}.`,\n      status: 503,\n      code: `HTTP_${error.status}`,\n    });\n  }\n  const transport = TRANSPORT_FAILURES[error.code];\n  if (transport) {\n    return new DataError({ ...common, message: `${transport.message} (${error.operation})${unknown}.`, status: transport.status, code: transport.code });\n  }\n\n  const httpStatus = error.status ?? 0;\n  const data = isObject(error.data) ? error.data : {};\n  // Only `data.reason` is a code; `error.reason` repeats the message text.\n  const reason = typeof data.reason === 'string' ? data.reason : undefined;\n  const code = error.code;\n  const msg = error.message;\n  const hint = codeHint(code, data) ?? error.repair;\n  let message = `${msg} (${code})`;\n  if (reason === ACCESS_REASONS.permissionMissing) {\n    message =\n      data.missingPermission === 'uns.delete'\n        ? `Deleting records requires the App key to hold uns.delete, and this App's key does not (${code}). ` +\n          'Model removal as a status change such as `archived`, or ask a workspace admin to grant uns.delete.'\n        : `The App key lacks ${typeof data.missingPermission === 'string' ? data.missingPermission : 'a permission'} for this operation (${code}); ask a workspace admin.`;\n  } else if (reason === ACCESS_REASONS.notGranted) {\n    message = `${message} This App's grant does not cover the collection or operation; ask a workspace admin to restore the grant.`;\n  } else if (reason === ACCESS_REASONS.notFound) {\n    message = `${message} The collection was archived or deleted; the data layer ensures the declared collections again.`;\n  } else if (httpStatus === 401) {\n    message = `Tier0 rejected the App credential for ${error.operation} (${code}). The platform injects TIER0_API_KEY; do not replace it.`;\n  } else if (hint) {\n    message = `${message} ${hint}`;\n  }\n\n  return new DataError({ ...common, message, status: appStatus(httpStatus, code), code, reason, upstreamStatus: httpStatus, details: data });\n}\n"]}

package/dist/cjs/data/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@tier0/sdk-v2/data` — server-only App data layer over Tier0 UNS collections.
+ *
+ *   import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';
+ *
+ *   const data = createDataClient({ collections: [workOrders] });
+ *   const open = await data.collection(workOrders).find({ status: 'OPEN' }, { limit: 50 }).toArray();
+ *
+ * Declarations are ensured in one batch on first access. Requires `zod` 4.
+ * Client code imports declarations and types from `@tier0/sdk-v2/data/define`.
+ */
+export { createDataClient } from './client.js';
+export { MAX_BATCH_QUERIES } from './client.js';
+export type { BatchQueries, BatchResults, DataClient, DataClientConfig, SettledBatchResults, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';
+export type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';
+export { MAX_ATOMIC_ITEMS, MAX_GET_IDS } from './collection.js';
+export type { BatchQuery, BulkOperation, CappedCount, Collection, CollectionQueries, Cursor, FoundPage, ValueCount, FindOneAndOptions, FindOptions, FindPageOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';
+export { currentDataSubject, runAsApp, runWithRequestContext } from './context.js';
+export { redactRestricted, SUBSCRIBE_IDLE_TIMEOUT_MS } from './subscribe.js';
+export type { ChangeEvent, CollectionChange, RecordChange, SubscribeOptions, SubscriptionEvent } from './subscribe.js';
+export { ACCESS_REASONS, DataError } from './error.js';
+export * from './declarations.js';
+export { toSortPairs } from './sort.js';
+export type { Filter, Sort, SortDirection, SortPairs } from './sort.js';

package/dist/cjs/data/index.js

@@ -0,0 +1,49 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSortPairs = exports.DataError = exports.ACCESS_REASONS = exports.SUBSCRIBE_IDLE_TIMEOUT_MS = exports.redactRestricted = exports.runWithRequestContext = exports.runAsApp = exports.currentDataSubject = exports.MAX_GET_IDS = exports.MAX_ATOMIC_ITEMS = exports.MAX_BATCH_QUERIES = exports.createDataClient = void 0;
+/**
+ * `@tier0/sdk-v2/data` — server-only App data layer over Tier0 UNS collections.
+ *
+ *   import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';
+ *
+ *   const data = createDataClient({ collections: [workOrders] });
+ *   const open = await data.collection(workOrders).find({ status: 'OPEN' }, { limit: 50 }).toArray();
+ *
+ * Declarations are ensured in one batch on first access. Requires `zod` 4.
+ * Client code imports declarations and types from `@tier0/sdk-v2/data/define`.
+ */
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "createDataClient", { enumerable: true, get: function () { return client_js_1.createDataClient; } });
+var client_js_2 = require("./client.js");
+Object.defineProperty(exports, "MAX_BATCH_QUERIES", { enumerable: true, get: function () { return client_js_2.MAX_BATCH_QUERIES; } });
+var collection_js_1 = require("./collection.js");
+Object.defineProperty(exports, "MAX_ATOMIC_ITEMS", { enumerable: true, get: function () { return collection_js_1.MAX_ATOMIC_ITEMS; } });
+Object.defineProperty(exports, "MAX_GET_IDS", { enumerable: true, get: function () { return collection_js_1.MAX_GET_IDS; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "currentDataSubject", { enumerable: true, get: function () { return context_js_1.currentDataSubject; } });
+Object.defineProperty(exports, "runAsApp", { enumerable: true, get: function () { return context_js_1.runAsApp; } });
+Object.defineProperty(exports, "runWithRequestContext", { enumerable: true, get: function () { return context_js_1.runWithRequestContext; } });
+var subscribe_js_1 = require("./subscribe.js");
+Object.defineProperty(exports, "redactRestricted", { enumerable: true, get: function () { return subscribe_js_1.redactRestricted; } });
+Object.defineProperty(exports, "SUBSCRIBE_IDLE_TIMEOUT_MS", { enumerable: true, get: function () { return subscribe_js_1.SUBSCRIBE_IDLE_TIMEOUT_MS; } });
+var error_js_1 = require("./error.js");
+Object.defineProperty(exports, "ACCESS_REASONS", { enumerable: true, get: function () { return error_js_1.ACCESS_REASONS; } });
+Object.defineProperty(exports, "DataError", { enumerable: true, get: function () { return error_js_1.DataError; } });
+__exportStar(require("./declarations.js"), exports);
+var sort_js_1 = require("./sort.js");
+Object.defineProperty(exports, "toSortPairs", { enumerable: true, get: function () { return sort_js_1.toSortPairs; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;GAUG;AACH,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA;AACzB,yCAAgD;AAAvC,8GAAA,iBAAiB,OAAA;AAG1B,iDAAgE;AAAvD,iHAAA,gBAAgB,OAAA;AAAE,4GAAA,WAAW,OAAA;AAEtC,2CAAmF;AAA1E,gHAAA,kBAAkB,OAAA;AAAE,sGAAA,QAAQ,OAAA;AAAE,mHAAA,qBAAqB,OAAA;AAC5D,+CAA6E;AAApE,gHAAA,gBAAgB,OAAA;AAAE,yHAAA,yBAAyB,OAAA;AAEpD,uCAAuD;AAA9C,0GAAA,cAAc,OAAA;AAAE,qGAAA,SAAS,OAAA;AAClC,oDAAkC;AAClC,qCAAwC;AAA/B,sGAAA,WAAW,OAAA","sourcesContent":["/**\n * `@tier0/sdk-v2/data` — server-only App data layer over Tier0 UNS collections.\n *\n *   import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';\n *\n *   const data = createDataClient({ collections: [workOrders] });\n *   const open = await data.collection(workOrders).find({ status: 'OPEN' }, { limit: 50 }).toArray();\n *\n * Declarations are ensured in one batch on first access. Requires `zod` 4.\n * Client code imports declarations and types from `@tier0/sdk-v2/data/define`.\n */\nexport { createDataClient } from './client.js';\nexport { MAX_BATCH_QUERIES } from './client.js';\nexport type { BatchQueries, BatchResults, DataClient, DataClientConfig, SettledBatchResults, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';\nexport type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';\nexport { MAX_ATOMIC_ITEMS, MAX_GET_IDS } from './collection.js';\nexport type { BatchQuery, BulkOperation, CappedCount, Collection, CollectionQueries, Cursor, FoundPage, ValueCount, FindOneAndOptions, FindOptions, FindPageOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';\nexport { currentDataSubject, runAsApp, runWithRequestContext } from './context.js';\nexport { redactRestricted, SUBSCRIBE_IDLE_TIMEOUT_MS } from './subscribe.js';\nexport type { ChangeEvent, CollectionChange, RecordChange, SubscribeOptions, SubscriptionEvent } from './subscribe.js';\nexport { ACCESS_REASONS, DataError } from './error.js';\nexport * from './declarations.js';\nexport { toSortPairs } from './sort.js';\nexport type { Filter, Sort, SortDirection, SortPairs } from './sort.js';\n"]}

package/dist/cjs/data/schema.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Zod 4 → UNS record schema normalizer, plus write-time validation.
+ *
+ * UNS stores one closed JSON-schema subset per collection: `type`,
+ * `properties`, `required`, `additionalProperties: false`, `items`, `enum`,
+ * `minimum`, `maximum`, declared `format`, `title`, `description`. `toRecordSchema` converts the
+ * `z.toJSONSchema` output into exactly that subset and rejects every other
+ * keyword with a concrete replacement, so a declaration that cannot be stored
+ * fails when it is compiled (an App can compile its declarations at build
+ * time) instead of on the first request.
+ */
+import { z } from 'zod';
+import { type CollectionDefinition } from './define.js';
+export type RecordSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean';
+export type EnumValue = string | number | boolean;
+export interface RecordSchema {
+    type: RecordSchemaType;
+    /** Display annotation; does not add range/date checks or convert stored values. */
+    format?: 'int32' | 'float' | 'double' | 'date-time';
+    title?: string;
+    description?: string;
+    properties?: Record<string, RecordSchema>;
+    required?: string[];
+    additionalProperties?: false;
+    items?: RecordSchema;
+    enum?: EnumValue[];
+    minimum?: number;
+    maximum?: number;
+}
+export interface NormalizedIndex {
+    path?: string;
+    paths?: string[];
+    unique?: true;
+    kind?: 'gin';
+    expireAfterSeconds?: number;
+}
+/** One ensure item, exactly as it is sent to `/uns/app/collections/ensure`. */
+export interface CompiledCollection {
+    alias: string;
+    recordSchema: RecordSchema;
+    indexes: NormalizedIndex[];
+    description?: string;
+}
+export interface SchemaIssue {
+    path: string;
+    message: string;
+}
+export declare class CollectionSchemaError extends Error {
+    readonly alias: string;
+    readonly issues: SchemaIssue[];
+    constructor(alias: string, issues: SchemaIssue[]);
+}
+/** UNS limits (unsmeta Schema.validate and collection indexes); title/description are UTF-8 bytes. */
+export declare const SCHEMA_LIMITS: {
+    readonly depth: 8;
+    readonly properties: 128;
+    readonly enumValues: 100;
+    readonly title: 512;
+    readonly description: 2048;
+    readonly indexes: 16;
+    readonly indexPaths: 3;
+    readonly ttlIndexes: 1;
+    readonly minExpireAfterSeconds: 60;
+    readonly maxExpireAfterSeconds: 31536000;
+};
+type JsonNode = Record<string, unknown>;
+/** Raw `z.toJSONSchema` output; exported for the snapshot tests. */
+export declare function zodJsonSchema(schema: z.ZodType): JsonNode;
+/** Converts a Zod object schema to the UNS record-schema subset or throws `CollectionSchemaError`. */
+export declare function toRecordSchema(alias: string, schema: z.ZodType): RecordSchema;
+/** Resolves a dotted business path in a record schema; array levels accept index segments. */
+export declare function recordSchemaAt(schema: RecordSchema, path: string): RecordSchema | undefined;
+/** Ensure payload for one declaration; memoized per definition object. */
+export declare function compileCollection(definition: CollectionDefinition): CompiledCollection;
+/** Splits `_id` / `_meta` off a document and strictly validates the body. */
+export declare function validateDocument(definition: CollectionDefinition, document: Record<string, unknown>): {
+    id?: string;
+    data: Record<string, unknown>;
+};
+/**
+ * Validates `data` of a transaction step. Fields filled by `bindings`
+ * (`data.<field>...`) are checked only for being declared; every literal
+ * field is strictly validated, and other required fields must be present.
+ */
+export declare function validateStepData(definition: CollectionDefinition, data: Record<string, unknown>, boundFields: readonly string[]): Record<string, unknown>;
+/** Validates update-operator documents against the declaration (paths and values). */
+export declare function validateUpdate(definition: CollectionDefinition, update: Record<string, unknown>): Record<string, unknown>;
+export {};