@gobing-ai/ts-utils 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# @gobing-ai/ts-utils
+
+Shared utilities — error types, date helpers, cursor-based pagination, role-based access control, API response builders, and output formatting. No platform dependencies; works in Bun, Node, and Cloudflare Workers.
+
+## Overview
+
+`ts-utils` provides small, composable utilities used across `ts-runtime`, `ts-db`, `ts-infra`, and application code. Each module is self-contained with zero external dependencies.
+
+| Module | Purpose |
+|--------|---------|
+| `errors` | Typed application errors (`AppError`, `NotFoundError`, `ValidationError`, etc.) |
+| `date` | `nowMs()`, timestamp ↔ Date conversion |
+| `cursor` | Base64url-encoded cursor-based pagination |
+| `access` | Zitadel + generic role-based access control (`hasRole`, `getRoles`) |
+| `api-response` | Standard API response envelope builders |
+| `output` | Human-readable output helpers (tables, JSON, etc.) |
+| `origin` | Request origin parsing |
+| `const` | Shared constants |
+
+## Architecture
+
+```mermaid
+classDiagram
+    class AppError {
+        +ErrorCode code
+        +string message
+    }
+
+    class NotFoundError {
+    }
+
+    class ValidationError {
+    }
+
+    class ConflictError {
+    }
+
+    class InternalError {
+        +unknown cause?
+    }
+
+    class ErrorCode {
+        <<enumeration>>
+        NotFound
+        Validation
+        Conflict
+        Internal
+    }
+
+    class CursorData {
+        <<interface>>
+        +string id
+        +number createdAt?
+        +number offset?
+    }
+
+    class CursorHelpers {
+        +createCursor(id, createdAt?, offset?) CursorData
+        +parseCursor(data) CursorData
+        +encodeCursor(cursor) string
+        +decodeCursor(encoded) string
+        +encodeCursorFromItem(id, createdAt?, offset?) string
+        +decodeAndParseCursor(encoded) CursorData
+        +buildCursorMeta(items, limit, hasMore) object
+    }
+
+    class DateHelpers {
+        +nowMs() number
+        +toMs(input) number | null
+        +fromMs(ms) Date | null
+    }
+
+    class AccessControl {
+        +hasRole(profile, role) boolean
+        +getRoles(profile) string[]
+    }
+
+    AppError <|-- NotFoundError
+    AppError <|-- ValidationError
+    AppError <|-- ConflictError
+    AppError <|-- InternalError
+    AppError --> ErrorCode
+```
+
+## How It Works
+
+### Error types
+
+Typed error hierarchy with error codes — consumers catch by type, not by string:
+
+```ts
+throw new NotFoundError(`User ${userId} not found`);
+throw new ValidationError('Email is required');
+throw new InternalError('DB connection lost', originalError);
+
+// Callers can discriminate:
+if (error instanceof NotFoundError) {
+    return new Response(null, { status: 404 });
+}
+if (isAppError(error)) {
+    // error.code is typed: 'NOT_FOUND' | 'VALIDATION' | 'CONFLICT' | 'INTERNAL'
+}
+```
+
+### Cursor-based pagination
+
+Encode a cursor from the last item in a page, return it to the client, decode on the next request:
+
+```ts
+import { encodeCursorFromItem, decodeAndParseCursor } from '@gobing-ai/ts-utils';
+
+// Page 1: encode cursor from last item
+const cursor = encodeCursorFromItem(lastItem.id, lastItem.createdAt);
+// → "eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6MTcwMDAwMDAwMH0"
+
+// Page 2: decode cursor from query param
+const parsed = decodeAndParseCursor(requestCursor);
+// → { id: "abc", createdAt: 1700000000 }
+
+// Build pagination metadata
+const meta = buildCursorMeta(items, limit, hasMore);
+// → { nextCursor: "eyJ...", hasMore: true, limit: 20 }
+```
+
+**Cursor flow:**
+
+```mermaid
+sequenceDiagram
+    Client->>API: GET /items?limit=20
+    API->>DB: SELECT ... LIMIT 20
+    DB-->>API: 20 rows
+    API->>API: encodeCursorFromItem(lastItem)
+    API-->>Client: { items: [...], nextCursor: "eyJ..." }
+
+    Client->>API: GET /items?limit=20&cursor=eyJ...
+    API->>API: decodeAndParseCursor("eyJ...")
+    API->>DB: SELECT ... WHERE id > "abc" LIMIT 20
+    DB-->>API: 20 rows
+    API-->>Client: { items: [...], nextCursor: "..." }
+```
+
+### Role-based access control
+
+Supports Zitadel IAM roles and generic role arrays/objects:
+
+```ts
+import { hasRole, getRoles } from '@gobing-ai/ts-utils';
+
+// Zitadel profile
+const profile = {
+    'urn:zitadel:iam:org:project:roles': { admin: 'project-1', viewer: 'project-1' },
+};
+hasRole(profile, 'admin'); // → true
+getRoles(profile); // → ['admin', 'viewer']
+
+// Generic roles array
+hasRole({ roles: ['editor', 'viewer'] }, 'editor'); // → true
+
+// Object-based roles
+hasRole({ roles: { admin: true } }, 'admin'); // → true
+```
+
+### Date utilities
+
+```ts
+import { nowMs, toMs, fromMs } from '@gobing-ai/ts-utils';
+
+const ts = nowMs(); // → 1700000000000
+
+toMs(new Date('2024-01-01')); // → 1704067200000
+toMs('2024-01-01'); // → 1704067200000
+toMs(null); // → null
+
+fromMs(1704067200000); // → Date('2024-01-01')
+fromMs(null); // → null
+```
+
+## Usage
+
+### Install
+
+```bash
+bun add @gobing-ai/ts-utils
+```
+
+### Common patterns
+
+```ts
+import {
+    AppError, NotFoundError, ValidationError, ConflictError, InternalError,
+    nowMs, toMs, fromMs,
+    encodeCursorFromItem, decodeAndParseCursor, buildCursorMeta,
+    hasRole, getRoles,
+} from '@gobing-ai/ts-utils';
+
+// Errors
+function getUser(id: string) {
+    const user = db.find(id);
+    if (!user) throw new NotFoundError(`User ${id} not found`);
+    return user;
+}
+
+// Pagination
+async function listUsers(limit: number, cursor?: string) {
+    const parsed = cursor ? decodeAndParseCursor(cursor) : undefined;
+    const users = await db.query(limit, parsed?.id);
+    const hasMore = users.length === limit;
+    return {
+        items: users,
+        ...buildCursorMeta(users, limit, hasMore),
+    };
+}
+
+// Auth guard
+function requireAdmin(profile: unknown) {
+    if (!hasRole(profile as Record<string, unknown>, 'admin')) {
+        throw new ForbiddenError('Admin access required');
+    }
+}
+```

package/dist/access.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Zitadel + generic role-based access control helpers.
+ *
+ * Supports Zitadel IAM role claims (`urn:zitadel:iam:org:project:roles`),
+ * generic `roles` arrays, and object-based role maps.
+ *
+ * If auth provider uses a different claim format, extend `hasRole`
+ * rather than forking this module.
+ */
+export declare function hasRole(profile: Record<string, unknown> | null | undefined, role: string): boolean;
+export declare function getRoles(profile: Record<string, unknown> | null | undefined): string[];
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CA+BlG;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAkCtF"}

package/dist/access.js

@@ -0,0 +1,75 @@
+/**
+ * Zitadel + generic role-based access control helpers.
+ *
+ * Supports Zitadel IAM role claims (`urn:zitadel:iam:org:project:roles`),
+ * generic `roles` arrays, and object-based role maps.
+ *
+ * If auth provider uses a different claim format, extend `hasRole`
+ * rather than forking this module.
+ */
+export function hasRole(profile, role) {
+    if (!profile)
+        return false;
+    if (!role || typeof role !== 'string')
+        return false;
+    const zitadelRoles = profile['urn:zitadel:iam:org:project:roles'];
+    if (zitadelRoles && typeof zitadelRoles === 'object') {
+        try {
+            if (zitadelRoles !== null && !Array.isArray(zitadelRoles) && Object.hasOwn(zitadelRoles, role)) {
+                return true;
+            }
+        }
+        catch {
+            // Continue to other role formats when host objects reject inspection.
+        }
+    }
+    const rolesArray = profile.roles;
+    if (Array.isArray(rolesArray)) {
+        return rolesArray.includes(role);
+    }
+    if (rolesArray && typeof rolesArray === 'object' && !Array.isArray(rolesArray)) {
+        try {
+            if (rolesArray !== null) {
+                return Object.hasOwn(rolesArray, role);
+            }
+        }
+        catch {
+            // Fall through.
+        }
+    }
+    return false;
+}
+export function getRoles(profile) {
+    if (!profile)
+        return [];
+    const roles = new Set();
+    const zitadelRoles = profile['urn:zitadel:iam:org:project:roles'];
+    if (zitadelRoles && typeof zitadelRoles === 'object' && zitadelRoles !== null && !Array.isArray(zitadelRoles)) {
+        try {
+            for (const key of Object.keys(zitadelRoles)) {
+                roles.add(key);
+            }
+        }
+        catch {
+            // Ignore host objects that reject key enumeration.
+        }
+    }
+    const rolesArray = profile.roles;
+    if (Array.isArray(rolesArray)) {
+        rolesArray.forEach((role) => {
+            if (typeof role === 'string')
+                roles.add(role);
+        });
+    }
+    if (rolesArray && typeof rolesArray === 'object' && rolesArray !== null && !Array.isArray(rolesArray)) {
+        try {
+            for (const key of Object.keys(rolesArray)) {
+                roles.add(key);
+            }
+        }
+        catch {
+            // Ignore host objects that reject key enumeration.
+        }
+    }
+    return Array.from(roles);
+}

package/dist/api-response.d.ts

@@ -0,0 +1,47 @@
+export declare const API_ERROR_CODES: {
+    readonly SUCCESS: 0;
+    readonly NOT_FOUND: 404;
+    readonly VALIDATION_ERROR: 422;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly CONFLICT: 409;
+    readonly INTERNAL_ERROR: 500;
+};
+export type ApiErrorCode = (typeof API_ERROR_CODES)[keyof typeof API_ERROR_CODES];
+export type ApiEnvelopeResult = 'success' | 'info' | 'warn' | 'error';
+export interface ApiSuccessEnvelope<T> {
+    code: 0;
+    message: string;
+    result: 'success' | 'info';
+    data: T;
+    meta?: {
+        total?: number;
+        limit?: number;
+        offset?: number;
+    };
+}
+export interface ApiErrorEnvelope {
+    result: 'warn' | 'error';
+    code: number;
+    message: string;
+    data: null;
+    details?: unknown;
+}
+export type ApiEnvelope<T> = ApiSuccessEnvelope<T> | ApiErrorEnvelope;
+export declare function successResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
+export declare function infoResponse<T>(data: T, message?: string): ApiSuccessEnvelope<T>;
+export declare function paginatedResponse<T>(data: T[], meta: {
+    total?: number;
+    limit?: number;
+    offset?: number;
+}, message?: string): ApiSuccessEnvelope<T[]>;
+export declare function errorResponse(code: number, message: string, details?: unknown): ApiErrorEnvelope;
+export declare function notFoundResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+export declare function validationErrorResponse(details: unknown, message?: string): ApiErrorEnvelope;
+export declare function badRequestResponse(message: string, details?: unknown): ApiErrorEnvelope;
+export declare function unauthorizedResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+export declare function forbiddenResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+export declare function conflictResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+export declare function internalErrorResponse(message?: string, details?: unknown): ApiErrorEnvelope;
+//# sourceMappingURL=api-response.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;;CASlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAElF,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;AAEtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAY,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOtF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,SAAgC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAOvG;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EACzD,OAAO,SAAgC,GACxC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAQzB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAahG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAuB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEpG;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,SAAsB,GAAG,gBAAgB,CAEzG;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEvF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,SAA4B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,iBAAiB,CAAC,OAAO,SAAqB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,gBAAgB,CAAC,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAEnG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,SAA0B,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAE5G"}

package/dist/api-response.js

@@ -0,0 +1,68 @@
+export const API_ERROR_CODES = {
+    SUCCESS: 0,
+    NOT_FOUND: 404,
+    VALIDATION_ERROR: 422,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    CONFLICT: 409,
+    INTERNAL_ERROR: 500,
+};
+export function successResponse(data, message = 'Success') {
+    return {
+        code: API_ERROR_CODES.SUCCESS,
+        message,
+        result: 'success',
+        data,
+    };
+}
+export function infoResponse(data, message = 'Data retrieved successfully') {
+    return {
+        code: API_ERROR_CODES.SUCCESS,
+        message,
+        result: 'info',
+        data,
+    };
+}
+export function paginatedResponse(data, meta, message = 'Data retrieved successfully') {
+    return {
+        code: API_ERROR_CODES.SUCCESS,
+        message,
+        result: 'info',
+        data,
+        meta,
+    };
+}
+export function errorResponse(code, message, details) {
+    const response = {
+        code,
+        message,
+        result: code >= 500 ? 'error' : 'warn',
+        data: null,
+    };
+    if (details !== undefined) {
+        response.details = details;
+    }
+    return response;
+}
+export function notFoundResponse(message = 'Resource not found', details) {
+    return errorResponse(API_ERROR_CODES.NOT_FOUND, message, details);
+}
+export function validationErrorResponse(details, message = 'Validation failed') {
+    return errorResponse(API_ERROR_CODES.VALIDATION_ERROR, message, details);
+}
+export function badRequestResponse(message, details) {
+    return errorResponse(API_ERROR_CODES.BAD_REQUEST, message, details);
+}
+export function unauthorizedResponse(message = 'Authentication required', details) {
+    return errorResponse(API_ERROR_CODES.UNAUTHORIZED, message, details);
+}
+export function forbiddenResponse(message = 'Access forbidden', details) {
+    return errorResponse(API_ERROR_CODES.FORBIDDEN, message, details);
+}
+export function conflictResponse(message = 'Resource conflict', details) {
+    return errorResponse(API_ERROR_CODES.CONFLICT, message, details);
+}
+export function internalErrorResponse(message = 'Internal server error', details) {
+    return errorResponse(API_ERROR_CODES.INTERNAL_ERROR, message, details);
+}

package/dist/const.d.ts

@@ -0,0 +1,3 @@
+export declare const LOG_CATEGORY_APP = "app";
+export declare const LOG_CATEGORY_CLI = "cli";
+//# sourceMappingURL=const.d.ts.map

package/dist/const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../src/const.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAEtC,eAAO,MAAM,gBAAgB,QAAQ,CAAC"}

package/dist/const.js

@@ -0,0 +1,2 @@
+export const LOG_CATEGORY_APP = 'app';
+export const LOG_CATEGORY_CLI = 'cli';

package/dist/cursor.d.ts

@@ -0,0 +1,20 @@
+export interface CursorData {
+    id: string;
+    createdAt?: number;
+    offset?: number;
+}
+export declare function createCursor(id: string, createdAt?: Date | number, offset?: number): CursorData;
+export declare function parseCursor(data: string | Record<string, unknown>): CursorData;
+export declare function encodeCursor(cursor: CursorData): string;
+export declare function decodeCursor(encoded: string): string;
+export declare function encodeCursorFromItem(id: string, createdAt?: Date | number, offset?: number): string;
+export declare function decodeAndParseCursor(encoded: string): CursorData;
+export declare function buildCursorMeta<T extends {
+    id: string;
+    createdAt?: number | Date;
+}>(items: T[], limit: number, hasMore: boolean): {
+    nextCursor?: string;
+    hasMore: boolean;
+    limit: number;
+};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAY/F;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAmB9E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEvD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEhE;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC/E,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACjB;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAc1D"}

package/dist/cursor.js

@@ -0,0 +1,61 @@
+import { toMs } from './date.js';
+export function createCursor(id, createdAt, offset) {
+    const cursor = { id };
+    if (createdAt !== undefined) {
+        const ms = toMs(createdAt);
+        if (ms !== null) {
+            cursor.createdAt = ms;
+        }
+    }
+    if (offset !== undefined) {
+        cursor.offset = offset;
+    }
+    return cursor;
+}
+export function parseCursor(data) {
+    const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('Invalid cursor: must be an object');
+    }
+    if (!parsed.id || typeof parsed.id !== 'string') {
+        throw new Error('Invalid cursor: missing or invalid id');
+    }
+    const result = { id: parsed.id };
+    if (typeof parsed.createdAt === 'number') {
+        result.createdAt = parsed.createdAt;
+    }
+    if (typeof parsed.offset === 'number') {
+        result.offset = parsed.offset;
+    }
+    return result;
+}
+export function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor)).toString('base64url');
+}
+export function decodeCursor(encoded) {
+    try {
+        return Buffer.from(encoded, 'base64url').toString('utf-8');
+    }
+    catch (error) {
+        throw new Error(`Invalid cursor encoding: ${String(error)}`);
+    }
+}
+export function encodeCursorFromItem(id, createdAt, offset) {
+    return encodeCursor(createCursor(id, createdAt, offset));
+}
+export function decodeAndParseCursor(encoded) {
+    return parseCursor(decodeCursor(encoded));
+}
+export function buildCursorMeta(items, limit, hasMore) {
+    const meta = {
+        hasMore,
+        limit,
+    };
+    if (hasMore) {
+        const lastItem = items.at(-1);
+        if (lastItem) {
+            meta.nextCursor = encodeCursorFromItem(lastItem.id, lastItem.createdAt);
+        }
+    }
+    return meta;
+}

package/dist/date.d.ts

@@ -0,0 +1,4 @@
+export declare function nowMs(): number;
+export declare function toMs(input: Date | number | string | null | undefined): number | null;
+export declare function fromMs(ms: number | null | undefined): Date | null;
+//# sourceMappingURL=date.d.ts.map

package/dist/date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../src/date.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQpF;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAGjE"}

package/dist/date.js

@@ -0,0 +1,19 @@
+export function nowMs() {
+    return Date.now();
+}
+export function toMs(input) {
+    if (input === null || input === undefined)
+        return null;
+    if (input instanceof Date)
+        return input.getTime();
+    if (typeof input === 'string') {
+        const parsed = new Date(input).getTime();
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    return Math.floor(input);
+}
+export function fromMs(ms) {
+    if (ms === null || ms === undefined || Number.isNaN(ms))
+        return null;
+    return new Date(ms);
+}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+export declare const ErrorCode: {
+    readonly NotFound: "NOT_FOUND";
+    readonly Validation: "VALIDATION";
+    readonly Conflict: "CONFLICT";
+    readonly Internal: "INTERNAL";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+}
+export declare class NotFoundError extends AppError {
+    constructor(message: string);
+}
+export declare class ValidationError extends AppError {
+    constructor(message: string);
+}
+export declare class ConflictError extends AppError {
+    constructor(message: string);
+}
+export declare class InternalError extends AppError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function isAppError(error: unknown): error is AppError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;gBAEb,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;CAK/C;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;gBAC7B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;aAGjB,KAAK,CAAC,EAAE,OAAO;gBADjC,OAAO,EAAE,MAAM,EACG,KAAK,CAAC,EAAE,OAAO,YAAA;CAKxC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/errors.js

@@ -0,0 +1,43 @@
+export const ErrorCode = {
+    NotFound: 'NOT_FOUND',
+    Validation: 'VALIDATION',
+    Conflict: 'CONFLICT',
+    Internal: 'INTERNAL',
+};
+export class AppError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+    }
+}
+export class NotFoundError extends AppError {
+    constructor(message) {
+        super(ErrorCode.NotFound, message);
+        this.name = 'NotFoundError';
+    }
+}
+export class ValidationError extends AppError {
+    constructor(message) {
+        super(ErrorCode.Validation, message);
+        this.name = 'ValidationError';
+    }
+}
+export class ConflictError extends AppError {
+    constructor(message) {
+        super(ErrorCode.Conflict, message);
+        this.name = 'ConflictError';
+    }
+}
+export class InternalError extends AppError {
+    cause;
+    constructor(message, cause) {
+        super(ErrorCode.Internal, message);
+        this.cause = cause;
+        this.name = 'InternalError';
+    }
+}
+export function isAppError(error) {
+    return error instanceof AppError;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './access';
+export * from './api-response';
+export * from './const';
+export * from './cursor';
+export * from './date';
+export * from './errors';
+export * from './origin';
+export * from './output';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './access.js';
+export * from './api-response.js';
+export * from './const.js';
+export * from './cursor.js';
+export * from './date.js';
+export * from './errors.js';
+export * from './origin.js';
+export * from './output.js';