@iveri/contracts 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @iveri/contracts
+
+The wire contract every Iveri service and frontend compiles against: shared types and plain
+enums, and nothing else.
+
+```bash
+pnpm add @iveri/contracts
+```
+
+```ts
+import { ApiResponse, CursorPage, ErrorCode, Maybe, Paginated, UUID } from '@iveri/contracts';
+```
+
+Import from the root barrel only — never `@iveri/contracts/dist/...`.
+
+## Zero runtime dependencies — the rule that defines this package
+
+This package ends up inside browser bundles, so it declares **no** `dependencies`,
+`peerDependencies` or `optionalDependencies`, and its compiled output imports nothing outside
+itself. Nothing from `@nestjs/*`, `typeorm`, `class-validator`, or `node:*` may ever appear
+here — not even as a type-only import.
+
+That is why it is a separate package from `@iveri/nest-sdk` rather than a folder inside it.
+It is enforced by `scripts/verify-zero-runtime-deps.mjs`, which runs as part of `build`: CI
+fails on the PR that adds a dependency, not on a frontend build weeks later.
+
+Anything needing a dependency belongs in `@iveri/nest-sdk` (backend) or `@iveri/react-kit`
+(frontend).
+
+## What is here
+
+### `type/`
+
+| Type                                                                          | Use                                                                                           |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `Nil`, `Maybe<T>`, `Nullable<T>`                                              | absent values. `Nullable` for anything crossing the wire — `JSON.stringify` drops `undefined` |
+| `UUID`                                                                        | template-literal shape hint; validation stays at the edge with `@IsUUID()`                    |
+| `Paginated<T>`                                                                | offset paging, where the client needs a total or arbitrary page jumps                         |
+| `CursorPage<T>`                                                               | cursor paging — the default for lists that grow while being read                              |
+| `ApiSuccessResponse<T>`, `ApiErrorResponse`, `ApiErrorBody`, `ApiResponse<T>` | the response envelope                                                                         |
+
+### `enum/`
+
+`ErrorCode` — the stable, machine-readable error classification carried in every error
+response. Clients branch on `code`; `message` is for humans and may change at any time.
+
+## What is deliberately **not** here yet
+
+`event/` (domain event envelope, topics) and `api/` (per-service request/response shapes) are
+in the plan but unwritten: no service defines them yet. They get added when a real consumer
+needs them, per the second-consumer rule — not in anticipation.
+
+## Adding to the contract
+
+- A new `ErrorCode` member is a **minor** version. Changing what an existing member means, or
+  removing one, is **major** — clients branch on these.
+- Widening a type is minor; narrowing it is major.
+- Breaking changes get a migration note in `CHANGELOG.md`. Services upgrade deliberately.
+
+## Build output
+
+Dual ESM + CJS (`dist/esm`, `dist/cjs`) behind an `exports` map, so NestJS `require`s it and
+Vite tree-shakes it. `sideEffects: false`.

package/dist/cjs/enum/error-code.enum.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Stable, machine-readable error classification carried in every
+ * {@link ApiErrorResponse}.
+ *
+ * A code is a **contract**: clients branch on it, so a member's meaning never
+ * changes and a member is never removed once published. Adding one is a minor
+ * version; repurposing one is a breaking change.
+ *
+ * Codes are deliberately coarser than HTTP status. Two different 404s that a
+ * client must handle differently deserve two codes; two that it handles
+ * identically share one.
+ */
+export declare enum ErrorCode {
+    /** Request body or query failed DTO validation. `details` lists the fields. */
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    /** Body could not be parsed at all — bad JSON, wrong content type. */
+    MALFORMED_REQUEST = "MALFORMED_REQUEST",
+    /** No credentials presented, or the token could not be verified. */
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    /** Credentials were well-formed but wrong. Never distinguishes unknown user from bad password. */
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    /** Token parsed and verified, but its expiry has passed. The client should refresh and retry. */
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    /** Authenticated, but the action is not permitted for this principal. */
+    FORBIDDEN = "FORBIDDEN",
+    /** Authenticated, but the principal's role lacks the required permission. */
+    INSUFFICIENT_PERMISSION = "INSUFFICIENT_PERMISSION",
+    /** The resource belongs to another tenant. Emitted instead of leaking its existence. */
+    TENANT_MISMATCH = "TENANT_MISMATCH",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    /** The request contradicts current state — a stale version, a closed aggregate. */
+    RESOURCE_CONFLICT = "RESOURCE_CONFLICT",
+    /** A uniqueness constraint would be violated. */
+    RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS",
+    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+    /** Syntactically valid and well-formed, but rejected by a business rule. */
+    UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    /** Catch-all for an unhandled failure. Details are logged, never returned. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** A third-party or downstream service returned an error we could not recover from. */
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    /** A dependency is unreachable or the service is shutting down. Retryable. */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /** A downstream call exceeded its deadline. Retryable. */
+    DEPENDENCY_TIMEOUT = "DEPENDENCY_TIMEOUT"
+}
+//# sourceMappingURL=error-code.enum.d.ts.map

package/dist/cjs/enum/error-code.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.enum.d.ts","sourceRoot":"","sources":["../../../src/enum/error-code.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,SAAS;IAEjB,+EAA+E;IAC/E,iBAAiB,sBAAsB;IACvC,sEAAsE;IACtE,iBAAiB,sBAAsB;IAGvC,oEAAoE;IACpE,eAAe,oBAAoB;IACnC,kGAAkG;IAClG,mBAAmB,wBAAwB;IAC3C,iGAAiG;IACjG,aAAa,kBAAkB;IAG/B,yEAAyE;IACzE,SAAS,cAAc;IACvB,6EAA6E;IAC7E,uBAAuB,4BAA4B;IACnD,wFAAwF;IACxF,eAAe,oBAAoB;IAGnC,kBAAkB,uBAAuB;IAGzC,mFAAmF;IACnF,iBAAiB,sBAAsB;IACvC,iDAAiD;IACjD,uBAAuB,4BAA4B;IAGnD,iBAAiB,sBAAsB;IACvC,4EAA4E;IAC5E,oBAAoB,yBAAyB;IAG7C,mBAAmB,wBAAwB;IAG3C,8EAA8E;IAC9E,cAAc,mBAAmB;IACjC,uFAAuF;IACvF,sBAAsB,2BAA2B;IACjD,8EAA8E;IAC9E,mBAAmB,wBAAwB;IAC3C,0DAA0D;IAC1D,kBAAkB,uBAAuB;CAC5C"}

package/dist/cjs/enum/error-code.enum.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = void 0;
+/**
+ * Stable, machine-readable error classification carried in every
+ * {@link ApiErrorResponse}.
+ *
+ * A code is a **contract**: clients branch on it, so a member's meaning never
+ * changes and a member is never removed once published. Adding one is a minor
+ * version; repurposing one is a breaking change.
+ *
+ * Codes are deliberately coarser than HTTP status. Two different 404s that a
+ * client must handle differently deserve two codes; two that it handles
+ * identically share one.
+ */
+var ErrorCode;
+(function (ErrorCode) {
+    // ── 400 Bad Request ─────────────────────────────────────────────────────
+    /** Request body or query failed DTO validation. `details` lists the fields. */
+    ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    /** Body could not be parsed at all — bad JSON, wrong content type. */
+    ErrorCode["MALFORMED_REQUEST"] = "MALFORMED_REQUEST";
+    // ── 401 Unauthorized ────────────────────────────────────────────────────
+    /** No credentials presented, or the token could not be verified. */
+    ErrorCode["UNAUTHENTICATED"] = "UNAUTHENTICATED";
+    /** Credentials were well-formed but wrong. Never distinguishes unknown user from bad password. */
+    ErrorCode["INVALID_CREDENTIALS"] = "INVALID_CREDENTIALS";
+    /** Token parsed and verified, but its expiry has passed. The client should refresh and retry. */
+    ErrorCode["TOKEN_EXPIRED"] = "TOKEN_EXPIRED";
+    // ── 403 Forbidden ───────────────────────────────────────────────────────
+    /** Authenticated, but the action is not permitted for this principal. */
+    ErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    /** Authenticated, but the principal's role lacks the required permission. */
+    ErrorCode["INSUFFICIENT_PERMISSION"] = "INSUFFICIENT_PERMISSION";
+    /** The resource belongs to another tenant. Emitted instead of leaking its existence. */
+    ErrorCode["TENANT_MISMATCH"] = "TENANT_MISMATCH";
+    // ── 404 Not Found ───────────────────────────────────────────────────────
+    ErrorCode["RESOURCE_NOT_FOUND"] = "RESOURCE_NOT_FOUND";
+    // ── 409 Conflict ────────────────────────────────────────────────────────
+    /** The request contradicts current state — a stale version, a closed aggregate. */
+    ErrorCode["RESOURCE_CONFLICT"] = "RESOURCE_CONFLICT";
+    /** A uniqueness constraint would be violated. */
+    ErrorCode["RESOURCE_ALREADY_EXISTS"] = "RESOURCE_ALREADY_EXISTS";
+    // ── 413 / 422 ───────────────────────────────────────────────────────────
+    ErrorCode["PAYLOAD_TOO_LARGE"] = "PAYLOAD_TOO_LARGE";
+    /** Syntactically valid and well-formed, but rejected by a business rule. */
+    ErrorCode["UNPROCESSABLE_ENTITY"] = "UNPROCESSABLE_ENTITY";
+    // ── 429 Too Many Requests ───────────────────────────────────────────────
+    ErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    // ── 5xx ─────────────────────────────────────────────────────────────────
+    /** Catch-all for an unhandled failure. Details are logged, never returned. */
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    /** A third-party or downstream service returned an error we could not recover from. */
+    ErrorCode["EXTERNAL_SERVICE_ERROR"] = "EXTERNAL_SERVICE_ERROR";
+    /** A dependency is unreachable or the service is shutting down. Retryable. */
+    ErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    /** A downstream call exceeded its deadline. Retryable. */
+    ErrorCode["DEPENDENCY_TIMEOUT"] = "DEPENDENCY_TIMEOUT";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+//# sourceMappingURL=error-code.enum.js.map

package/dist/cjs/enum/error-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.enum.js","sourceRoot":"","sources":["../../../src/enum/error-code.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,IAAY,SAiDX;AAjDD,WAAY,SAAS;IACjB,2EAA2E;IAC3E,+EAA+E;IAC/E,oDAAuC,CAAA;IACvC,sEAAsE;IACtE,oDAAuC,CAAA;IAEvC,2EAA2E;IAC3E,oEAAoE;IACpE,gDAAmC,CAAA;IACnC,kGAAkG;IAClG,wDAA2C,CAAA;IAC3C,iGAAiG;IACjG,4CAA+B,CAAA;IAE/B,2EAA2E;IAC3E,yEAAyE;IACzE,oCAAuB,CAAA;IACvB,6EAA6E;IAC7E,gEAAmD,CAAA;IACnD,wFAAwF;IACxF,gDAAmC,CAAA;IAEnC,2EAA2E;IAC3E,sDAAyC,CAAA;IAEzC,2EAA2E;IAC3E,mFAAmF;IACnF,oDAAuC,CAAA;IACvC,iDAAiD;IACjD,gEAAmD,CAAA;IAEnD,2EAA2E;IAC3E,oDAAuC,CAAA;IACvC,4EAA4E;IAC5E,0DAA6C,CAAA;IAE7C,2EAA2E;IAC3E,wDAA2C,CAAA;IAE3C,2EAA2E;IAC3E,8EAA8E;IAC9E,8CAAiC,CAAA;IACjC,uFAAuF;IACvF,8DAAiD,CAAA;IACjD,8EAA8E;IAC9E,wDAA2C,CAAA;IAC3C,0DAA0D;IAC1D,sDAAyC,CAAA;AAC7C,CAAC,EAjDW,SAAS,yBAAT,SAAS,QAiDpB"}

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

@@ -0,0 +1,2 @@
+export * from './error-code.enum.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/enum/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/enum/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/cjs/enum/index.js

@@ -0,0 +1,18 @@
+"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 });
+__exportStar(require("./error-code.enum.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/enum/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './enum/index.js';
+export * from './type/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"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 });
+__exportStar(require("./enum/index.js"), exports);
+__exportStar(require("./type/index.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,kDAAgC"}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "commonjs"
+}

package/dist/cjs/type/api-response.type.d.ts

@@ -0,0 +1,63 @@
+import type { ErrorCode } from '../enum/error-code.enum.js';
+import type { Maybe } from './nil.type.js';
+/**
+ * Envelope for a successful HTTP response.
+ *
+ * Every service wraps its payload in this shape, so a client can branch on
+ * `success` before touching anything else and never has to guess whether a
+ * 200 body is data or an error report.
+ *
+ * @typeParam T - the response payload type.
+ */
+export interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+}
+/**
+ * The error half of {@link ApiErrorResponse}.
+ *
+ * `message` is for humans and may change at any time — clients branch on
+ * `code`, never on message text.
+ */
+export interface ApiErrorBody {
+    /** Stable, machine-readable classification. The only field safe to branch on. */
+    code: ErrorCode;
+    /** Human-readable summary. Safe to surface to a developer, not to an end user. */
+    message: string;
+    /**
+     * Structured context — which field failed validation, which constraint was
+     * violated. Never contains secrets, tokens, or raw upstream payloads.
+     */
+    details?: Maybe<Record<string, unknown>>;
+    /**
+     * The request's correlation id, echoed so a user can quote it in a support
+     * ticket and the whole request can be pulled out of the logs.
+     */
+    correlationId?: Maybe<string>;
+}
+/**
+ * Envelope for a failed HTTP response, emitted by the SDK's global exception
+ * filter for every non-2xx status.
+ */
+export interface ApiErrorResponse {
+    success: false;
+    error: ApiErrorBody;
+    /** ISO-8601 timestamp of when the error was rendered. */
+    timestamp: string;
+    /** Request path that produced the error, without the query string. */
+    path: string;
+}
+/**
+ * Discriminated union of both envelopes. Narrow on `success`:
+ *
+ * ```ts
+ * if (!response.success) {
+ *     return handle(response.error.code);
+ * }
+ * use(response.data);
+ * ```
+ *
+ * @typeParam T - the payload type on the success branch.
+ */
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+//# sourceMappingURL=api-response.type.d.ts.map

package/dist/cjs/type/api-response.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.type.d.ts","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAC;IAEhB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IAEpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC"}

package/dist/cjs/type/api-response.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=api-response.type.js.map

package/dist/cjs/type/api-response.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.type.js","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":""}

package/dist/cjs/type/cursor-page.type.d.ts

@@ -0,0 +1,27 @@
+import type { Nullable } from './nil.type.js';
+/**
+ * A cursor-paginated slice of a collection.
+ *
+ * The default for anything that grows while it is being read — delivery logs,
+ * captures, conversation messages. A cursor is anchored to a row rather than a
+ * position, so inserts during paging cannot make the reader skip or repeat.
+ *
+ * The cursor is an **opaque** string. Callers pass it back verbatim and never
+ * parse it; its encoding is an implementation detail of the service that issued
+ * it and may change without a version bump.
+ *
+ * @typeParam T - the element type of a single row.
+ */
+export interface CursorPage<T> {
+    /** The rows for this page, in the requested order. */
+    items: T[];
+    /** Cursor to pass as `after` for the next page, or `null` when the end is reached. */
+    nextCursor: Nullable<string>;
+    /**
+     * Whether another page exists. Equivalent to `nextCursor !== null`, exposed
+     * separately so UI code can render a "load more" affordance without
+     * reasoning about the cursor at all.
+     */
+    hasMore: boolean;
+}
+//# sourceMappingURL=cursor-page.type.d.ts.map

package/dist/cjs/type/cursor-page.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-page.type.d.ts","sourceRoot":"","sources":["../../../src/type/cursor-page.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,sDAAsD;IACtD,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,sFAAsF;IACtF,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE7B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CACpB"}

package/dist/cjs/type/cursor-page.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cursor-page.type.js.map

package/dist/cjs/type/cursor-page.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-page.type.js","sourceRoot":"","sources":["../../../src/type/cursor-page.type.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,6 @@
+export * from './api-response.type.js';
+export * from './cursor-page.type.js';
+export * from './nil.type.js';
+export * from './paginated.type.js';
+export * from './uuid.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/type/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}

package/dist/cjs/type/index.js

@@ -0,0 +1,22 @@
+"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 });
+__exportStar(require("./api-response.type.js"), exports);
+__exportStar(require("./cursor-page.type.js"), exports);
+__exportStar(require("./nil.type.js"), exports);
+__exportStar(require("./paginated.type.js"), exports);
+__exportStar(require("./uuid.type.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,wDAAsC;AACtC,gDAA8B;AAC9B,sDAAoC;AACpC,iDAA+B"}

package/dist/cjs/type/nil.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Represents a value that is either `null` or `undefined`.
+ *
+ * Useful for excluding nullish values from union types via `Exclude<T, Nil>`
+ * or for explicitly modelling absent values.
+ */
+export type Nil = null | undefined;
+/**
+ * A value that may be `T` or absent (`null` / `undefined`).
+ *
+ * Prefer `Maybe<T>` over inline `T | null | undefined` for consistency
+ * across services.
+ */
+export type Maybe<T> = T | Nil;
+/**
+ * A value that may be `T` or `null` (but never `undefined`).
+ *
+ * Use this for anything that crosses the wire: `JSON.stringify` drops
+ * `undefined` properties, so a nullable API field must be `null` to survive
+ * serialization.
+ */
+export type Nullable<T> = T | null;
+//# sourceMappingURL=nil.type.d.ts.map

package/dist/cjs/type/nil.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nil.type.d.ts","sourceRoot":"","sources":["../../../src/type/nil.type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/dist/cjs/type/nil.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=nil.type.js.map

package/dist/cjs/type/nil.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nil.type.js","sourceRoot":"","sources":["../../../src/type/nil.type.ts"],"names":[],"mappings":""}

package/dist/cjs/type/paginated.type.d.ts

@@ -0,0 +1,21 @@
+/**
+ * An offset-paginated slice of a collection.
+ *
+ * Use this where the client needs to jump to an arbitrary page or show a total
+ * count. Where the collection is large, append-only, or mutating under the
+ * reader (delivery logs, captures, messages), prefer `CursorPage<T>` — offset
+ * paging over a moving list skips and repeats rows.
+ *
+ * @typeParam T - the element type of a single row.
+ */
+export interface Paginated<T> {
+    /** The rows for the requested page, in the requested order. */
+    items: T[];
+    /** Total rows matching the query across every page, ignoring `limit`/`offset`. */
+    total: number;
+    /** Maximum rows the caller asked for. `items.length` may be smaller on the last page. */
+    limit: number;
+    /** Rows skipped before this page. Zero-based. */
+    offset: number;
+}
+//# sourceMappingURL=paginated.type.d.ts.map

package/dist/cjs/type/paginated.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated.type.d.ts","sourceRoot":"","sources":["../../../src/type/paginated.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IAEd,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IAEd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/dist/cjs/type/paginated.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=paginated.type.js.map

package/dist/cjs/type/paginated.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated.type.js","sourceRoot":"","sources":["../../../src/type/paginated.type.ts"],"names":[],"mappings":""}

package/dist/cjs/type/uuid.type.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A UUID string value.
+ *
+ * Structurally identical to the `UUID` type from `node:crypto`, but declared
+ * here rather than re-exported: `@iveri/contracts` compiles into browser
+ * bundles, and importing from `node:crypto` — even type-only — would force
+ * every frontend to depend on `@types/node`.
+ *
+ * This is a shape hint, not a guarantee. Validation happens at the edge with
+ * `@IsUUID()` on the request DTO.
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}`;
+//# sourceMappingURL=uuid.type.d.ts.map

package/dist/cjs/type/uuid.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.type.d.ts","sourceRoot":"","sources":["../../../src/type/uuid.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC"}

package/dist/cjs/type/uuid.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=uuid.type.js.map

package/dist/cjs/type/uuid.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.type.js","sourceRoot":"","sources":["../../../src/type/uuid.type.ts"],"names":[],"mappings":""}

package/dist/esm/enum/error-code.enum.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Stable, machine-readable error classification carried in every
+ * {@link ApiErrorResponse}.
+ *
+ * A code is a **contract**: clients branch on it, so a member's meaning never
+ * changes and a member is never removed once published. Adding one is a minor
+ * version; repurposing one is a breaking change.
+ *
+ * Codes are deliberately coarser than HTTP status. Two different 404s that a
+ * client must handle differently deserve two codes; two that it handles
+ * identically share one.
+ */
+export declare enum ErrorCode {
+    /** Request body or query failed DTO validation. `details` lists the fields. */
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    /** Body could not be parsed at all — bad JSON, wrong content type. */
+    MALFORMED_REQUEST = "MALFORMED_REQUEST",
+    /** No credentials presented, or the token could not be verified. */
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    /** Credentials were well-formed but wrong. Never distinguishes unknown user from bad password. */
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    /** Token parsed and verified, but its expiry has passed. The client should refresh and retry. */
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    /** Authenticated, but the action is not permitted for this principal. */
+    FORBIDDEN = "FORBIDDEN",
+    /** Authenticated, but the principal's role lacks the required permission. */
+    INSUFFICIENT_PERMISSION = "INSUFFICIENT_PERMISSION",
+    /** The resource belongs to another tenant. Emitted instead of leaking its existence. */
+    TENANT_MISMATCH = "TENANT_MISMATCH",
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
+    /** The request contradicts current state — a stale version, a closed aggregate. */
+    RESOURCE_CONFLICT = "RESOURCE_CONFLICT",
+    /** A uniqueness constraint would be violated. */
+    RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS",
+    PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+    /** Syntactically valid and well-formed, but rejected by a business rule. */
+    UNPROCESSABLE_ENTITY = "UNPROCESSABLE_ENTITY",
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
+    /** Catch-all for an unhandled failure. Details are logged, never returned. */
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    /** A third-party or downstream service returned an error we could not recover from. */
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    /** A dependency is unreachable or the service is shutting down. Retryable. */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /** A downstream call exceeded its deadline. Retryable. */
+    DEPENDENCY_TIMEOUT = "DEPENDENCY_TIMEOUT"
+}
+//# sourceMappingURL=error-code.enum.d.ts.map

package/dist/esm/enum/error-code.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.enum.d.ts","sourceRoot":"","sources":["../../../src/enum/error-code.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,SAAS;IAEjB,+EAA+E;IAC/E,iBAAiB,sBAAsB;IACvC,sEAAsE;IACtE,iBAAiB,sBAAsB;IAGvC,oEAAoE;IACpE,eAAe,oBAAoB;IACnC,kGAAkG;IAClG,mBAAmB,wBAAwB;IAC3C,iGAAiG;IACjG,aAAa,kBAAkB;IAG/B,yEAAyE;IACzE,SAAS,cAAc;IACvB,6EAA6E;IAC7E,uBAAuB,4BAA4B;IACnD,wFAAwF;IACxF,eAAe,oBAAoB;IAGnC,kBAAkB,uBAAuB;IAGzC,mFAAmF;IACnF,iBAAiB,sBAAsB;IACvC,iDAAiD;IACjD,uBAAuB,4BAA4B;IAGnD,iBAAiB,sBAAsB;IACvC,4EAA4E;IAC5E,oBAAoB,yBAAyB;IAG7C,mBAAmB,wBAAwB;IAG3C,8EAA8E;IAC9E,cAAc,mBAAmB;IACjC,uFAAuF;IACvF,sBAAsB,2BAA2B;IACjD,8EAA8E;IAC9E,mBAAmB,wBAAwB;IAC3C,0DAA0D;IAC1D,kBAAkB,uBAAuB;CAC5C"}

package/dist/esm/enum/error-code.enum.js

@@ -0,0 +1,57 @@
+/**
+ * Stable, machine-readable error classification carried in every
+ * {@link ApiErrorResponse}.
+ *
+ * A code is a **contract**: clients branch on it, so a member's meaning never
+ * changes and a member is never removed once published. Adding one is a minor
+ * version; repurposing one is a breaking change.
+ *
+ * Codes are deliberately coarser than HTTP status. Two different 404s that a
+ * client must handle differently deserve two codes; two that it handles
+ * identically share one.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // ── 400 Bad Request ─────────────────────────────────────────────────────
+    /** Request body or query failed DTO validation. `details` lists the fields. */
+    ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    /** Body could not be parsed at all — bad JSON, wrong content type. */
+    ErrorCode["MALFORMED_REQUEST"] = "MALFORMED_REQUEST";
+    // ── 401 Unauthorized ────────────────────────────────────────────────────
+    /** No credentials presented, or the token could not be verified. */
+    ErrorCode["UNAUTHENTICATED"] = "UNAUTHENTICATED";
+    /** Credentials were well-formed but wrong. Never distinguishes unknown user from bad password. */
+    ErrorCode["INVALID_CREDENTIALS"] = "INVALID_CREDENTIALS";
+    /** Token parsed and verified, but its expiry has passed. The client should refresh and retry. */
+    ErrorCode["TOKEN_EXPIRED"] = "TOKEN_EXPIRED";
+    // ── 403 Forbidden ───────────────────────────────────────────────────────
+    /** Authenticated, but the action is not permitted for this principal. */
+    ErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    /** Authenticated, but the principal's role lacks the required permission. */
+    ErrorCode["INSUFFICIENT_PERMISSION"] = "INSUFFICIENT_PERMISSION";
+    /** The resource belongs to another tenant. Emitted instead of leaking its existence. */
+    ErrorCode["TENANT_MISMATCH"] = "TENANT_MISMATCH";
+    // ── 404 Not Found ───────────────────────────────────────────────────────
+    ErrorCode["RESOURCE_NOT_FOUND"] = "RESOURCE_NOT_FOUND";
+    // ── 409 Conflict ────────────────────────────────────────────────────────
+    /** The request contradicts current state — a stale version, a closed aggregate. */
+    ErrorCode["RESOURCE_CONFLICT"] = "RESOURCE_CONFLICT";
+    /** A uniqueness constraint would be violated. */
+    ErrorCode["RESOURCE_ALREADY_EXISTS"] = "RESOURCE_ALREADY_EXISTS";
+    // ── 413 / 422 ───────────────────────────────────────────────────────────
+    ErrorCode["PAYLOAD_TOO_LARGE"] = "PAYLOAD_TOO_LARGE";
+    /** Syntactically valid and well-formed, but rejected by a business rule. */
+    ErrorCode["UNPROCESSABLE_ENTITY"] = "UNPROCESSABLE_ENTITY";
+    // ── 429 Too Many Requests ───────────────────────────────────────────────
+    ErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
+    // ── 5xx ─────────────────────────────────────────────────────────────────
+    /** Catch-all for an unhandled failure. Details are logged, never returned. */
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+    /** A third-party or downstream service returned an error we could not recover from. */
+    ErrorCode["EXTERNAL_SERVICE_ERROR"] = "EXTERNAL_SERVICE_ERROR";
+    /** A dependency is unreachable or the service is shutting down. Retryable. */
+    ErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    /** A downstream call exceeded its deadline. Retryable. */
+    ErrorCode["DEPENDENCY_TIMEOUT"] = "DEPENDENCY_TIMEOUT";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=error-code.enum.js.map

package/dist/esm/enum/error-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.enum.js","sourceRoot":"","sources":["../../../src/enum/error-code.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,SAiDX;AAjDD,WAAY,SAAS;IACjB,2EAA2E;IAC3E,+EAA+E;IAC/E,oDAAuC,CAAA;IACvC,sEAAsE;IACtE,oDAAuC,CAAA;IAEvC,2EAA2E;IAC3E,oEAAoE;IACpE,gDAAmC,CAAA;IACnC,kGAAkG;IAClG,wDAA2C,CAAA;IAC3C,iGAAiG;IACjG,4CAA+B,CAAA;IAE/B,2EAA2E;IAC3E,yEAAyE;IACzE,oCAAuB,CAAA;IACvB,6EAA6E;IAC7E,gEAAmD,CAAA;IACnD,wFAAwF;IACxF,gDAAmC,CAAA;IAEnC,2EAA2E;IAC3E,sDAAyC,CAAA;IAEzC,2EAA2E;IAC3E,mFAAmF;IACnF,oDAAuC,CAAA;IACvC,iDAAiD;IACjD,gEAAmD,CAAA;IAEnD,2EAA2E;IAC3E,oDAAuC,CAAA;IACvC,4EAA4E;IAC5E,0DAA6C,CAAA;IAE7C,2EAA2E;IAC3E,wDAA2C,CAAA;IAE3C,2EAA2E;IAC3E,8EAA8E;IAC9E,8CAAiC,CAAA;IACjC,uFAAuF;IACvF,8DAAiD,CAAA;IACjD,8EAA8E;IAC9E,wDAA2C,CAAA;IAC3C,0DAA0D;IAC1D,sDAAyC,CAAA;AAC7C,CAAC,EAjDW,SAAS,KAAT,SAAS,QAiDpB"}

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

@@ -0,0 +1,2 @@
+export * from './error-code.enum.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/enum/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/enum/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/esm/enum/index.js

@@ -0,0 +1,2 @@
+export * from './error-code.enum.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/enum/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export * from './enum/index.js';
+export * from './type/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from './enum/index.js';
+export * from './type/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}

package/dist/esm/type/api-response.type.d.ts

@@ -0,0 +1,63 @@
+import type { ErrorCode } from '../enum/error-code.enum.js';
+import type { Maybe } from './nil.type.js';
+/**
+ * Envelope for a successful HTTP response.
+ *
+ * Every service wraps its payload in this shape, so a client can branch on
+ * `success` before touching anything else and never has to guess whether a
+ * 200 body is data or an error report.
+ *
+ * @typeParam T - the response payload type.
+ */
+export interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+}
+/**
+ * The error half of {@link ApiErrorResponse}.
+ *
+ * `message` is for humans and may change at any time — clients branch on
+ * `code`, never on message text.
+ */
+export interface ApiErrorBody {
+    /** Stable, machine-readable classification. The only field safe to branch on. */
+    code: ErrorCode;
+    /** Human-readable summary. Safe to surface to a developer, not to an end user. */
+    message: string;
+    /**
+     * Structured context — which field failed validation, which constraint was
+     * violated. Never contains secrets, tokens, or raw upstream payloads.
+     */
+    details?: Maybe<Record<string, unknown>>;
+    /**
+     * The request's correlation id, echoed so a user can quote it in a support
+     * ticket and the whole request can be pulled out of the logs.
+     */
+    correlationId?: Maybe<string>;
+}
+/**
+ * Envelope for a failed HTTP response, emitted by the SDK's global exception
+ * filter for every non-2xx status.
+ */
+export interface ApiErrorResponse {
+    success: false;
+    error: ApiErrorBody;
+    /** ISO-8601 timestamp of when the error was rendered. */
+    timestamp: string;
+    /** Request path that produced the error, without the query string. */
+    path: string;
+}
+/**
+ * Discriminated union of both envelopes. Narrow on `success`:
+ *
+ * ```ts
+ * if (!response.success) {
+ *     return handle(response.error.code);
+ * }
+ * use(response.data);
+ * ```
+ *
+ * @typeParam T - the payload type on the success branch.
+ */
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+//# sourceMappingURL=api-response.type.d.ts.map

package/dist/esm/type/api-response.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.type.d.ts","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IACzB,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAC;IAEhB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IAEpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC"}

package/dist/esm/type/api-response.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-response.type.js.map

package/dist/esm/type/api-response.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.type.js","sourceRoot":"","sources":["../../../src/type/api-response.type.ts"],"names":[],"mappings":""}

package/dist/esm/type/cursor-page.type.d.ts

@@ -0,0 +1,27 @@
+import type { Nullable } from './nil.type.js';
+/**
+ * A cursor-paginated slice of a collection.
+ *
+ * The default for anything that grows while it is being read — delivery logs,
+ * captures, conversation messages. A cursor is anchored to a row rather than a
+ * position, so inserts during paging cannot make the reader skip or repeat.
+ *
+ * The cursor is an **opaque** string. Callers pass it back verbatim and never
+ * parse it; its encoding is an implementation detail of the service that issued
+ * it and may change without a version bump.
+ *
+ * @typeParam T - the element type of a single row.
+ */
+export interface CursorPage<T> {
+    /** The rows for this page, in the requested order. */
+    items: T[];
+    /** Cursor to pass as `after` for the next page, or `null` when the end is reached. */
+    nextCursor: Nullable<string>;
+    /**
+     * Whether another page exists. Equivalent to `nextCursor !== null`, exposed
+     * separately so UI code can render a "load more" affordance without
+     * reasoning about the cursor at all.
+     */
+    hasMore: boolean;
+}
+//# sourceMappingURL=cursor-page.type.d.ts.map

package/dist/esm/type/cursor-page.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-page.type.d.ts","sourceRoot":"","sources":["../../../src/type/cursor-page.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,sDAAsD;IACtD,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,sFAAsF;IACtF,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE7B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;CACpB"}

package/dist/esm/type/cursor-page.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cursor-page.type.js.map

package/dist/esm/type/cursor-page.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-page.type.js","sourceRoot":"","sources":["../../../src/type/cursor-page.type.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,6 @@
+export * from './api-response.type.js';
+export * from './cursor-page.type.js';
+export * from './nil.type.js';
+export * from './paginated.type.js';
+export * from './uuid.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/type/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}

package/dist/esm/type/index.js

@@ -0,0 +1,6 @@
+export * from './api-response.type.js';
+export * from './cursor-page.type.js';
+export * from './nil.type.js';
+export * from './paginated.type.js';
+export * from './uuid.type.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC"}

package/dist/esm/type/nil.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Represents a value that is either `null` or `undefined`.
+ *
+ * Useful for excluding nullish values from union types via `Exclude<T, Nil>`
+ * or for explicitly modelling absent values.
+ */
+export type Nil = null | undefined;
+/**
+ * A value that may be `T` or absent (`null` / `undefined`).
+ *
+ * Prefer `Maybe<T>` over inline `T | null | undefined` for consistency
+ * across services.
+ */
+export type Maybe<T> = T | Nil;
+/**
+ * A value that may be `T` or `null` (but never `undefined`).
+ *
+ * Use this for anything that crosses the wire: `JSON.stringify` drops
+ * `undefined` properties, so a nullable API field must be `null` to survive
+ * serialization.
+ */
+export type Nullable<T> = T | null;
+//# sourceMappingURL=nil.type.d.ts.map

package/dist/esm/type/nil.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nil.type.d.ts","sourceRoot":"","sources":["../../../src/type/nil.type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,GAAG,GAAG,IAAI,GAAG,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC"}

package/dist/esm/type/nil.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=nil.type.js.map

package/dist/esm/type/nil.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nil.type.js","sourceRoot":"","sources":["../../../src/type/nil.type.ts"],"names":[],"mappings":""}

package/dist/esm/type/paginated.type.d.ts

@@ -0,0 +1,21 @@
+/**
+ * An offset-paginated slice of a collection.
+ *
+ * Use this where the client needs to jump to an arbitrary page or show a total
+ * count. Where the collection is large, append-only, or mutating under the
+ * reader (delivery logs, captures, messages), prefer `CursorPage<T>` — offset
+ * paging over a moving list skips and repeats rows.
+ *
+ * @typeParam T - the element type of a single row.
+ */
+export interface Paginated<T> {
+    /** The rows for the requested page, in the requested order. */
+    items: T[];
+    /** Total rows matching the query across every page, ignoring `limit`/`offset`. */
+    total: number;
+    /** Maximum rows the caller asked for. `items.length` may be smaller on the last page. */
+    limit: number;
+    /** Rows skipped before this page. Zero-based. */
+    offset: number;
+}
+//# sourceMappingURL=paginated.type.d.ts.map

package/dist/esm/type/paginated.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated.type.d.ts","sourceRoot":"","sources":["../../../src/type/paginated.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IACxB,+DAA+D;IAC/D,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IAEd,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IAEd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/dist/esm/type/paginated.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=paginated.type.js.map

package/dist/esm/type/paginated.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated.type.js","sourceRoot":"","sources":["../../../src/type/paginated.type.ts"],"names":[],"mappings":""}

package/dist/esm/type/uuid.type.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A UUID string value.
+ *
+ * Structurally identical to the `UUID` type from `node:crypto`, but declared
+ * here rather than re-exported: `@iveri/contracts` compiles into browser
+ * bundles, and importing from `node:crypto` — even type-only — would force
+ * every frontend to depend on `@types/node`.
+ *
+ * This is a shape hint, not a guarantee. Validation happens at the edge with
+ * `@IsUUID()` on the request DTO.
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}`;
+//# sourceMappingURL=uuid.type.d.ts.map

package/dist/esm/type/uuid.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.type.d.ts","sourceRoot":"","sources":["../../../src/type/uuid.type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC"}

package/dist/esm/type/uuid.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=uuid.type.js.map

package/dist/esm/type/uuid.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.type.js","sourceRoot":"","sources":["../../../src/type/uuid.type.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@iveri/contracts",
+  "version": "0.1.0",
+  "description": "Wire contracts shared by every Iveri backend and frontend. Zero runtime dependencies.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iverihq/iveri-contracts.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@9.12.0",
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cjs/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rimraf dist tsconfig.*.tsbuildinfo",
+    "build": "pnpm clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ./scripts/write-dist-package-json.mjs && node ./scripts/verify-zero-runtime-deps.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "prettier": "@iveri/prettier-config",
+  "devDependencies": {
+    "@iveri/eslint-config": "^0.1.0",
+    "@iveri/prettier-config": "^0.1.0",
+    "@iveri/tsconfig": "^0.1.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.7",
+    "eslint": "^9.18.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3"
+  }
+}