@tier0/sdk-v2 0.0.0-stage → 0.1.0

package/dist/esm/data/define.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Collection declarations — the single source of truth for App data.
+ *
+ * An App declares every collection with `defineCollection(...)` and passes the
+ * list to `createDataClient({ collections })`. The client ensures that list in
+ * one batch on first data access: a missing collection is created, a
+ * declaration wider than storage widens it, and nothing is ever narrowed.
+ *
+ * This module is pure (Zod types only) so declarations, API input schemas and
+ * build-time checks can import it without pulling in the runtime client.
+ */
+import type { z } from 'zod';
+/** Collection alias: unique per App, case-insensitive. */
+export declare const ALIAS_PATTERN: RegExp;
+/** UNS: one ensure takes 1–64 declarations, and an App owns at most 64 collections. */
+export declare const MAX_COLLECTIONS = 64;
+/** UNS: collection description length in characters. */
+export declare const MAX_DESCRIPTION_LENGTH = 512;
+/** Seeds are inserted in atomic chunks of 200 during the first request; keep them a baseline, not a data import. */
+export declare const MAX_SEED_DOCUMENTS = 1000;
+/** Same shape as UNS `collectionCreate` indexes, limited to record indexes. */
+export interface IndexSpec {
+    /** Business field path without `data.`, e.g. `code` or `customer.id`. */
+    path?: string;
+    /** Compound index, at most 3 paths. Mutually exclusive with `path`. */
+    paths?: string[];
+    unique?: boolean;
+    /** `btree` (default) or `gin` for one object/array path; GIN cannot be unique. */
+    kind?: 'btree' | 'gin';
+}
+/** System metadata of a stored record. Times are Unix milliseconds. */
+export interface RecordMeta {
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export type CollectionSchema = z.ZodObject;
+/** A seed document: a full record plus the fixed `_id` it is inserted with. */
+export type SeedDoc<S extends CollectionSchema> = z.input<S> & {
+    _id: string;
+};
+export interface CollectionDefinition<S extends CollectionSchema = CollectionSchema> {
+    readonly alias: string;
+    /** Zod 4 object schema of the record body (no `_id` / `_meta`). */
+    readonly schema: S;
+    readonly indexes: readonly IndexSpec[];
+    readonly description?: string;
+    /**
+     * Baseline records, written only when ensure reports this collection as
+     * `created`. Never re-applied to an existing collection.
+     */
+    readonly seed?: readonly SeedDoc<S>[];
+}
+/** A stored record as services read it: `{ _id, ...fields, _meta }`. */
+export type Doc<C extends CollectionDefinition> = z.output<C['schema']> & {
+    _id: string;
+    _meta: RecordMeta;
+};
+/** A record to insert: the schema input plus an optional caller-chosen `_id`. */
+export type NewDoc<C extends CollectionDefinition> = z.input<C['schema']> & {
+    _id?: string;
+};
+export declare function defineCollection<S extends CollectionSchema>(definition: {
+    alias: string;
+    schema: S;
+    indexes?: IndexSpec[];
+    description?: string;
+    seed?: SeedDoc<S>[];
+}): CollectionDefinition<S>;

package/dist/esm/data/define.js

@@ -0,0 +1,27 @@
+/** Collection alias: unique per App, case-insensitive. */
+export const ALIAS_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,62}$/;
+/** UNS: one ensure takes 1–64 declarations, and an App owns at most 64 collections. */
+export const MAX_COLLECTIONS = 64;
+/** UNS: collection description length in characters. */
+export const MAX_DESCRIPTION_LENGTH = 512;
+/** Seeds are inserted in atomic chunks of 200 during the first request; keep them a baseline, not a data import. */
+export const MAX_SEED_DOCUMENTS = 1000;
+export function defineCollection(definition) {
+    if (!ALIAS_PATTERN.test(definition.alias)) {
+        throw new Error(`Collection alias "${definition.alias}" must match ${ALIAS_PATTERN} (letters, digits, "_" or "-", starting with a letter).`);
+    }
+    if (definition.description && [...definition.description].length > MAX_DESCRIPTION_LENGTH) {
+        throw new Error(`Collection "${definition.alias}": description is longer than ${MAX_DESCRIPTION_LENGTH} characters.`);
+    }
+    if (definition.seed && definition.seed.length > MAX_SEED_DOCUMENTS) {
+        throw new Error(`Collection "${definition.alias}": at most ${MAX_SEED_DOCUMENTS} seed documents (got ${definition.seed.length}). Seeds are a baseline written on creation, not a bulk import.`);
+    }
+    return Object.freeze({
+        alias: definition.alias,
+        schema: definition.schema,
+        indexes: Object.freeze([...(definition.indexes ?? [])]),
+        ...(definition.description ? { description: definition.description } : {}),
+        ...(definition.seed ? { seed: Object.freeze([...definition.seed]) } : {}),
+    });
+}
+//# sourceMappingURL=define.js.map

package/dist/esm/data/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../../src/data/define.ts"],"names":[],"mappings":"AAaA,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAC7D,uFAAuF;AACvF,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,wDAAwD;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,oHAAoH;AACpH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAiDvC,MAAM,UAAU,gBAAgB,CAA6B,UAM5D;IACC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,qBAAqB,UAAU,CAAC,KAAK,gBAAgB,aAAa,yDAAyD,CAC5H,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,WAAW,IAAI,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;QAC1F,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,KAAK,iCAAiC,sBAAsB,cAAc,CAAC,CAAC;IACxH,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,eAAe,UAAU,CAAC,KAAK,cAAc,kBAAkB,wBAAwB,UAAU,CAAC,IAAI,CAAC,MAAM,iEAAiE,CAC/K,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;QACvD,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Collection declarations — the single source of truth for App data.\n *\n * An App declares every collection with `defineCollection(...)` and passes the\n * list to `createDataClient({ collections })`. The client ensures that list in\n * one batch on first data access: a missing collection is created, a\n * declaration wider than storage widens it, and nothing is ever narrowed.\n *\n * This module is pure (Zod types only) so declarations, API input schemas and\n * build-time checks can import it without pulling in the runtime client.\n */\nimport type { z } from 'zod';\n\n/** Collection alias: unique per App, case-insensitive. */\nexport const ALIAS_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,62}$/;\n/** UNS: one ensure takes 1–64 declarations, and an App owns at most 64 collections. */\nexport const MAX_COLLECTIONS = 64;\n/** UNS: collection description length in characters. */\nexport const MAX_DESCRIPTION_LENGTH = 512;\n/** Seeds are inserted in atomic chunks of 200 during the first request; keep them a baseline, not a data import. */\nexport const MAX_SEED_DOCUMENTS = 1000;\n\n/** Same shape as UNS `collectionCreate` indexes, limited to record indexes. */\nexport interface IndexSpec {\n  /** Business field path without `data.`, e.g. `code` or `customer.id`. */\n  path?: string;\n  /** Compound index, at most 3 paths. Mutually exclusive with `path`. */\n  paths?: string[];\n  unique?: boolean;\n  /** `btree` (default) or `gin` for one object/array path; GIN cannot be unique. */\n  kind?: 'btree' | 'gin';\n}\n\n/** System metadata of a stored record. Times are Unix milliseconds. */\nexport interface RecordMeta {\n  revision: number;\n  createdAt: number;\n  updatedAt: number;\n}\n\nexport type CollectionSchema = z.ZodObject;\n\n/** A seed document: a full record plus the fixed `_id` it is inserted with. */\nexport type SeedDoc<S extends CollectionSchema> = z.input<S> & { _id: string };\n\nexport interface CollectionDefinition<S extends CollectionSchema = CollectionSchema> {\n  readonly alias: string;\n  /** Zod 4 object schema of the record body (no `_id` / `_meta`). */\n  readonly schema: S;\n  readonly indexes: readonly IndexSpec[];\n  readonly description?: string;\n  /**\n   * Baseline records, written only when ensure reports this collection as\n   * `created`. Never re-applied to an existing collection.\n   */\n  readonly seed?: readonly SeedDoc<S>[];\n}\n\n/** A stored record as services read it: `{ _id, ...fields, _meta }`. */\nexport type Doc<C extends CollectionDefinition> = z.output<C['schema']> & {\n  _id: string;\n  _meta: RecordMeta;\n};\n\n/** A record to insert: the schema input plus an optional caller-chosen `_id`. */\nexport type NewDoc<C extends CollectionDefinition> = z.input<C['schema']> & {\n  _id?: string;\n};\n\nexport function defineCollection<S extends CollectionSchema>(definition: {\n  alias: string;\n  schema: S;\n  indexes?: IndexSpec[];\n  description?: string;\n  seed?: SeedDoc<S>[];\n}): CollectionDefinition<S> {\n  if (!ALIAS_PATTERN.test(definition.alias)) {\n    throw new Error(\n      `Collection alias \"${definition.alias}\" must match ${ALIAS_PATTERN} (letters, digits, \"_\" or \"-\", starting with a letter).`,\n    );\n  }\n  if (definition.description && [...definition.description].length > MAX_DESCRIPTION_LENGTH) {\n    throw new Error(`Collection \"${definition.alias}\": description is longer than ${MAX_DESCRIPTION_LENGTH} characters.`);\n  }\n  if (definition.seed && definition.seed.length > MAX_SEED_DOCUMENTS) {\n    throw new Error(\n      `Collection \"${definition.alias}\": at most ${MAX_SEED_DOCUMENTS} seed documents (got ${definition.seed.length}). Seeds are a baseline written on creation, not a bulk import.`,\n    );\n  }\n  return Object.freeze({\n    alias: definition.alias,\n    schema: definition.schema,\n    indexes: Object.freeze([...(definition.indexes ?? [])]),\n    ...(definition.description ? { description: definition.description } : {}),\n    ...(definition.seed ? { seed: Object.freeze([...definition.seed]) } : {}),\n  });\n}\n"]}

package/dist/esm/data/error.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Runtime failures of a data call, missing credentials included, are a
+ * `DataError`. The SDK's UNS client does the HTTP exchange; its `UnsV2Error`
+ * (kept as `cause`) is translated here, and the data layer raises its own codes
+ * (BATCH_LIMIT_EXCEEDED, WRITE_ERRORS, ...). `status` is the HTTP status the App
+ * should answer its own caller with. Writes that fail validation throw
+ * `ZodError`; programming or platform errors, such as invalid client options or
+ * a malformed data subject from the gateway, throw `TypeError`.
+ */
+import { type UnsV2Error } from '../uns-v2/client.js';
+/**
+ * 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.
+ */
+export declare const ACCESS_REASONS: {
+    /** 403: the collection exists, but this App's grant does not cover it or the operation. */
+    readonly notGranted: "COLLECTION_NOT_GRANTED";
+    /** 403 or 404: the collection is gone (hard-deleted or archived). */
+    readonly notFound: "COLLECTION_NOT_FOUND";
+    /** 403: the grant covers the operation, the App key lacks `data.missingPermission`. */
+    readonly permissionMissing: "APP_PERMISSION_MISSING";
+};
+export declare class DataError extends Error {
+    /** HTTP status the App should answer with (see `appStatus`). */
+    readonly status: number;
+    /** UNS error code, e.g. `DUPLICATE_KEY`, or a data-layer code. */
+    readonly code: string;
+    /** Stable `data.reason` code, e.g. `COLLECTION_NOT_FOUND` (see ACCESS_REASONS). */
+    readonly reason?: string;
+    /** HTTP status UNS answered with; 0 when no response arrived. */
+    readonly upstreamStatus: number;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    /** A write may have reached UNS: reconcile before replaying it with a new idempotency key. */
+    readonly outcomeUnknown: boolean;
+    /** The `data` object of the UNS error envelope, or data-layer details. */
+    readonly details: Record<string, unknown>;
+    constructor(init: {
+        message: string;
+        status: number;
+        code: string;
+        reason?: string;
+        upstreamStatus?: number;
+        requestId?: string;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+/**
+ * Maps an upstream UNS status 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,
+ * and a retryable 403 becomes 503 instead of looking like a denied action.
+ */
+export declare function appStatus(upstream: number, retryable?: boolean): number;
+/** Translates a failed UNS call of the SDK client. */
+export declare function toDataError(error: UnsV2Error): DataError;

package/dist/esm/data/error.js

@@ -0,0 +1,178 @@
+/**
+ * Runtime failures of a data call, missing credentials included, are a
+ * `DataError`. The SDK's UNS client does the HTTP exchange; its `UnsV2Error`
+ * (kept as `cause`) is translated here, and the data layer raises its own codes
+ * (BATCH_LIMIT_EXCEEDED, WRITE_ERRORS, ...). `status` is the HTTP status the App
+ * should answer its own caller with. Writes that fail validation throw
+ * `ZodError`; programming or platform errors, such as invalid client options or
+ * a malformed data subject from the gateway, throw `TypeError`.
+ */
+import { UnsV2OutcomeUnknownError } from '../uns-v2/client.js';
+/**
+ * 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.
+ */
+export const 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',
+};
+export 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;
+    retryable;
+    /** A write may have reached UNS: reconcile before replaying it with a new idempotency key. */
+    outcomeUnknown;
+    /** 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.retryable = init.retryable ?? false;
+        this.outcomeUnknown = init.outcomeUnknown ?? false;
+        this.details = init.details ?? {};
+    }
+}
+/**
+ * Maps an upstream UNS status 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,
+ * and a retryable 403 becomes 503 instead of looking like a denied action.
+ */
+export function appStatus(upstream, retryable = false) {
+    if (upstream === 401)
+        return 502;
+    // A retryable refusal is a platform state, not the caller's permission:
+    // e.g. FORBIDDEN "hosted App is not ready" right after an import.
+    if (upstream === 403 && retryable)
+        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.',
+};
+/** `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, retryable: true, message: 'UNS did not answer in time' },
+    UNS_V2_TRANSPORT_ERROR: { code: 'DATA_UNREACHABLE', status: 503, retryable: true, message: 'Cannot reach the Tier0 data service' },
+    UNS_V2_PROTOCOL_ERROR: { code: 'DATA_BAD_RESPONSE', status: 502, retryable: false, 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. */
+export function toDataError(error) {
+    const outcomeUnknown = error instanceof UnsV2OutcomeUnknownError;
+    // An ingress or load balancer answers 502/503/504 without the UNS envelope during
+    // rolling releases and pod restarts: retryable, 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({
+            message: `The Tier0 data gateway answered ${error.operation} with HTTP ${error.status}; retry shortly${outcomeUnknown ? ' (the write outcome is unknown)' : ''}.`,
+            status: 503,
+            code: `HTTP_${error.status}`,
+            upstreamStatus: error.status,
+            retryable: true,
+            outcomeUnknown,
+            cause: error,
+        });
+    }
+    const transport = TRANSPORT_FAILURES[error.code];
+    if (transport) {
+        return new DataError({
+            message: `${transport.message} (${error.operation})${outcomeUnknown ? '; the write outcome is unknown' : ''}.`,
+            status: transport.status,
+            code: transport.code,
+            upstreamStatus: error.status,
+            retryable: transport.retryable,
+            outcomeUnknown,
+            cause: error,
+        });
+    }
+    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 retryable = error.retryable || httpStatus === 503 || httpStatus === 504;
+    const code = error.code;
+    const msg = error.message;
+    const hint = codeHint(code, data);
+    let message = `${msg} (${code})`;
+    if (httpStatus === 403 && retryable) {
+        message = `${msg} (${code}). The platform is still preparing this App; retry shortly.`;
+    }
+    else if (reason === 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 === 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 === 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({
+        message,
+        status: appStatus(httpStatus, retryable),
+        code,
+        reason,
+        upstreamStatus: httpStatus,
+        requestId: error.requestId,
+        retryable,
+        outcomeUnknown,
+        details: data,
+        cause: error,
+    });
+}
+//# sourceMappingURL=error.js.map

package/dist/esm/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 { UnsV2OutcomeUnknownError, type UnsV2Error } 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  readonly retryable: boolean;\n  /** A write may have reached UNS: reconcile before replaying it with a new idempotency key. */\n  readonly outcomeUnknown: boolean;\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    retryable?: boolean;\n    outcomeUnknown?: boolean;\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.retryable = init.retryable ?? false;\n    this.outcomeUnknown = init.outcomeUnknown ?? false;\n    this.details = init.details ?? {};\n  }\n}\n\n/**\n * Maps an upstream UNS status to the status the App answers its own caller\n * 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 * and a retryable 403 becomes 503 instead of looking like a denied action.\n */\nexport function appStatus(upstream: number, retryable = false): number {\n  if (upstream === 401) return 502;\n  // A retryable refusal is a platform state, not the caller's permission:\n  // e.g. FORBIDDEN \"hosted App is not ready\" right after an import.\n  if (upstream === 403 && retryable) 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};\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; retryable: boolean; message: string }> = {\n  UNS_V2_TRANSPORT_TIMEOUT: { code: 'DATA_TIMEOUT', status: 503, retryable: true, message: 'UNS did not answer in time' },\n  UNS_V2_TRANSPORT_ERROR: { code: 'DATA_UNREACHABLE', status: 503, retryable: true, message: 'Cannot reach the Tier0 data service' },\n  UNS_V2_PROTOCOL_ERROR: { code: 'DATA_BAD_RESPONSE', status: 502, retryable: false, 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. */\nexport function toDataError(error: UnsV2Error): DataError {\n  const outcomeUnknown = error instanceof UnsV2OutcomeUnknownError;\n  // An ingress or load balancer answers 502/503/504 without the UNS envelope during\n  // rolling releases and pod restarts: retryable, like any unavailable upstream.\n  // UNS v2 routes answer every other error with the envelope (401/403/429 included),\n  // so other 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      message: `The Tier0 data gateway answered ${error.operation} with HTTP ${error.status}; retry shortly${outcomeUnknown ? ' (the write outcome is unknown)' : ''}.`,\n      status: 503,\n      code: `HTTP_${error.status}`,\n      upstreamStatus: error.status,\n      retryable: true,\n      outcomeUnknown,\n      cause: error,\n    });\n  }\n  const transport = TRANSPORT_FAILURES[error.code];\n  if (transport) {\n    return new DataError({\n      message: `${transport.message} (${error.operation})${outcomeUnknown ? '; the write outcome is unknown' : ''}.`,\n      status: transport.status,\n      code: transport.code,\n      upstreamStatus: error.status,\n      retryable: transport.retryable,\n      outcomeUnknown,\n      cause: error,\n    });\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 retryable = error.retryable || httpStatus === 503 || httpStatus === 504;\n  const code = error.code;\n  const msg = error.message;\n  const hint = codeHint(code, data);\n  let message = `${msg} (${code})`;\n  if (httpStatus === 403 && retryable) {\n    message = `${msg} (${code}). The platform is still preparing this App; retry shortly.`;\n  } else 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({\n    message,\n    status: appStatus(httpStatus, retryable),\n    code,\n    reason,\n    upstreamStatus: httpStatus,\n    requestId: error.requestId,\n    retryable,\n    outcomeUnknown,\n    details: data,\n    cause: error,\n  });\n}\n"]}

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

@@ -0,0 +1,21 @@
+/**
+ * `@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 type { DataClient, DataClientConfig, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';
+export type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';
+export { MAX_ATOMIC_ITEMS } from './collection.js';
+export type { BulkOperation, Collection, Cursor, FindOneAndOptions, FindOptions, FindPageOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';
+export { currentDataSubject, runAsApp, runWithRequestContext } from './context.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/esm/data/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@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_ATOMIC_ITEMS } from './collection.js';
+export { currentDataSubject, runAsApp, runWithRequestContext } from './context.js';
+export { ACCESS_REASONS, DataError } from './error.js';
+export * from './declarations.js';
+export { toSortPairs } from './sort.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvD,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC","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 type { DataClient, DataClientConfig, TransactAction, TransactResult, TransactResultItem, TransactStep } from './client.js';\nexport type { DataEnvironment, EnsureConflict, EnsureNote, EnsureResult, EnsureState, EnsureWarning, Logger } from './bootstrap.js';\nexport { MAX_ATOMIC_ITEMS } from './collection.js';\nexport type { BulkOperation, Collection, Cursor, FindOneAndOptions, FindOptions, FindPageOptions, Projection, Update, UpdateOptions, WithMeta } from './collection.js';\nexport { currentDataSubject, runAsApp, runWithRequestContext } from './context.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/esm/data/schema.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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`, `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;
+    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';
+}
+/** 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;
+};
+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 {};