common-typescript-utils 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+## [1.0.1](https://github.com/mini-app-polis/common-typescript-utils/compare/v1.0.0...v1.0.1) (2026-04-05)
+
+
+### Bug Fixes
+
+* correct doppler project, upgrade secrets-fetch-action to v2 ([02de9d4](https://github.com/mini-app-polis/common-typescript-utils/commit/02de9d40ff1ae3251b076cb2fef3d80d139a8e45))
+
+# 1.0.0 (2026-04-05)
+
+
+### Bug Fixes
+
+* build requirements ([f7d748c](https://github.com/mini-app-polis/common-typescript-utils/commit/f7d748c0d815df474f04420f862a8162feb7c907))
+* ci ([f1a05f3](https://github.com/mini-app-polis/common-typescript-utils/commit/f1a05f379c2dbcc2ec621b63ca03fe0a1a6e6bb7))
+
+
+### Features
+
+* Initial commit ([d460636](https://github.com/mini-app-polis/common-typescript-utils/commit/d46063636d7e127d8be1a129cc746b788ec23dcf))
+
+# Changelog

package/README.md

@@ -0,0 +1,95 @@
+# common-typescript-utils
+
+Shared TypeScript utilities for the MiniAppPolis ecosystem. The TypeScript counterpart to [`common-python-utils`](https://github.com/mini-app-polis/common-python-utils).
+
+## Installation
+
+```bash
+npm install common-typescript-utils
+```
+
+## Modules
+
+### `createLogger(service)`
+
+Structured logger with dev/prod modes. In production emits JSON to stdout/stderr; in development emits emoji-prefixed human-readable lines.
+
+```typescript
+import { createLogger } from "common-typescript-utils";
+
+const logger = createLogger("my-service");
+
+logger.info({ event: "server_started", category: "infra", context: { port: 3000 } });
+logger.error({ event: "db_failure", category: "data", error: new Error("timeout") });
+logger.start("initializing");   // 🚀 in dev, INFO JSON in prod
+logger.success("ready");        // ✅ in dev, INFO JSON in prod
+logger.failure("crashed");      // ❌ in dev, ERROR JSON in prod
+```
+
+Log categories: `"infra" | "pipeline" | "data" | "api"`
+
+### `verifyClerkToken(token, jwksUrl)`
+
+Raw JWKS + RS256 JWT verification using the Web Crypto API. Runtime-agnostic — works in Node 18+, Cloudflare Workers, and Deno without any polyfills.
+
+```typescript
+import { verifyClerkToken } from "common-typescript-utils";
+
+const payload = await verifyClerkToken(token, "https://your-clerk-instance.clerk.accounts.dev/.well-known/jwks.json");
+// payload.sub — owner_id
+// payload.email — resolved from email or email_addresses
+```
+
+JWKS responses and imported keys are cached in-memory with a 1-hour TTL.
+
+### `success` / `successList` / `error` / `CommonErrors`
+
+Standard API response envelopes.
+
+```typescript
+import { success, successList, CommonErrors } from "common-typescript-utils";
+
+return c.json(success({ id: 1, name: "foo" }));
+// { data: { id: 1, name: "foo" }, meta: { version: "v1" } }
+
+return c.json(successList(items), 200);
+// { data: [...], meta: { version: "v1", count: 3 } }
+
+return c.json(CommonErrors.notFound("User"), 404);
+// { error: { code: "NOT_FOUND", message: "User not found" } }
+```
+
+Available helpers: `unauthorized()`, `forbidden()`, `notFound(resource?)`, `badRequest(message)`, `internalError(message?)`, `validationError(zodIssues)`.
+
+### Schemas
+
+Generic Zod schemas for common API patterns.
+
+```typescript
+import { PaginationSchema, IdParamSchema, UserRoleSchema } from "common-typescript-utils";
+
+const { page, limit } = PaginationSchema.parse(req.query);
+const { id } = IdParamSchema.parse(req.params);
+const role = UserRoleSchema.parse(req.body.role); // "user" | "admin"
+```
+
+> **Note:** Domain-specific schemas (WCS divisions, session/checkin status, etc.) live in the repos that own those domains.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## Release
+
+Releases are automated via semantic-release on push to `main`. Requires `NPM_TOKEN` and `GITHUB_TOKEN` secrets.
+
+```
+feat:     → minor bump
+fix:      → patch bump
+feat!:    → major bump
+```

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+export type ClerkPayload = {
+    sub: string;
+    email?: string;
+} & Record<string, unknown>;
+export declare function verifyClerkToken(token: string, jwksUrl: string): Promise<ClerkPayload>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyD5B,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkC5F"}

package/dist/auth.js

@@ -0,0 +1,77 @@
+const CACHE_TTL_MS = 60 * 60 * 1000;
+let cache = null;
+const keyCache = new Map();
+function base64UrlDecode(str) {
+    const padded = str
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(str.length + ((4 - (str.length % 4)) % 4), "=");
+    return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+function decodePayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new Error("Malformed token");
+    const json = new TextDecoder().decode(base64UrlDecode(parts[1]));
+    return JSON.parse(json);
+}
+async function fetchJwks(jwksUrl) {
+    const now = Date.now();
+    if (cache && now < cache.expiry)
+        return cache.jwks;
+    const res = await fetch(jwksUrl);
+    if (!res.ok)
+        throw new Error(`JWKS fetch failed: ${res.status}`);
+    const jwks = (await res.json());
+    if (!jwks.keys?.length)
+        throw new Error("No keys in JWKS");
+    cache = { jwks, expiry: now + CACHE_TTL_MS };
+    return jwks;
+}
+async function importKeyForKid(jwksUrl, kid) {
+    const now = Date.now();
+    const cached = keyCache.get(kid);
+    if (cached && now < cached.expiry)
+        return cached.key;
+    const jwks = await fetchJwks(jwksUrl);
+    const jwk = jwks.keys.find((k) => k.kid === kid);
+    if (!jwk)
+        throw new Error(`No JWK for kid ${kid}`);
+    const key = await crypto.subtle.importKey("jwk", jwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+    keyCache.set(kid, { key, expiry: now + CACHE_TTL_MS });
+    return key;
+}
+export async function verifyClerkToken(token, jwksUrl) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new Error("Malformed token");
+    const headerJson = new TextDecoder().decode(base64UrlDecode(parts[0]));
+    const header = JSON.parse(headerJson);
+    if (!header.kid)
+        throw new Error("Token missing kid");
+    const key = await importKeyForKid(jwksUrl, header.kid);
+    const signingInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    const signature = base64UrlDecode(parts[2]);
+    const sigBuf = new Uint8Array(signature.byteLength);
+    sigBuf.set(signature);
+    const valid = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, sigBuf, signingInput);
+    if (!valid)
+        throw new Error("Invalid signature");
+    const payload = decodePayload(token);
+    const exp = payload.exp;
+    if (typeof exp === "number" && Date.now() / 1000 >= exp) {
+        throw new Error("Token expired");
+    }
+    const sub = payload.sub;
+    if (typeof sub !== "string" || !sub)
+        throw new Error("Invalid subject");
+    const email = typeof payload.email === "string"
+        ? payload.email
+        : typeof payload.email_addresses?.[0]
+            ?.email_address === "string"
+            ? payload.email_addresses[0]
+                .email_address
+            : undefined;
+    return { ...payload, sub, email };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./logger.js";
+export * from "./response.js";
+export * from "./auth.js";
+export * from "./schemas.js";
+//# 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,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./logger.js";
+export * from "./response.js";
+export * from "./auth.js";
+export * from "./schemas.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+export type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+export type LogCategory = "infra" | "pipeline" | "data" | "api";
+export interface LogParams {
+    event: string;
+    category: LogCategory;
+    context?: Record<string, unknown>;
+}
+export interface Logger {
+    debug: (params: LogParams) => void;
+    info: (params: LogParams) => void;
+    warn: (params: LogParams) => void;
+    error: (params: LogParams & {
+        error?: unknown;
+    }) => void;
+    start: (event: string, context?: Record<string, unknown>) => void;
+    success: (event: string, context?: Record<string, unknown>) => void;
+    failure: (event: string, context?: Record<string, unknown>) => void;
+}
+export declare function createLogger(service: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC;AAEhE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACzD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAClE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACrE;AA0CD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA6FpD"}

package/dist/logger.js

@@ -0,0 +1,117 @@
+function isProd() {
+    return process.env.NODE_ENV === "production";
+}
+function isoTimestamp() {
+    return new Date().toISOString();
+}
+function mergeErrorContext(context, error) {
+    const out = context ? { ...context } : {};
+    if (error instanceof Error) {
+        out.error_message = error.message;
+        out.error_stack = error.stack;
+    }
+    else if (error !== undefined) {
+        out.error = error;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function emojiForLevel(level) {
+    switch (level) {
+        case "DEBUG":
+            return "🔍";
+        case "INFO":
+            return "📋";
+        case "WARN":
+            return "⚠️";
+        case "ERROR":
+            return "❌";
+        default: {
+            const _exhaustive = level;
+            return _exhaustive;
+        }
+    }
+}
+function writeLine(level, line) {
+    if (level === "ERROR")
+        console.error(line);
+    else
+        console.log(line);
+}
+export function createLogger(service) {
+    function emitProd(level, category, event, context) {
+        const payload = {
+            timestamp: isoTimestamp(),
+            service,
+            level,
+            category,
+            event,
+        };
+        if (context && Object.keys(context).length > 0) {
+            payload.context = context;
+        }
+        const line = JSON.stringify(payload);
+        writeLine(level, line);
+    }
+    function emitDev(level, category, event, context) {
+        const ctx = context && Object.keys(context).length > 0
+            ? ` ${JSON.stringify(context)}`
+            : "";
+        const line = `${emojiForLevel(level)} [${level}] [${category}] ${event}${ctx}`;
+        writeLine(level, line);
+    }
+    function emit(level, category, event, context) {
+        if (isProd())
+            emitProd(level, category, event, context);
+        else
+            emitDev(level, category, event, context);
+    }
+    return {
+        debug(params) {
+            emit("DEBUG", params.category, params.event, params.context);
+        },
+        info(params) {
+            emit("INFO", params.category, params.event, params.context);
+        },
+        warn(params) {
+            emit("WARN", params.category, params.event, params.context);
+        },
+        error(params) {
+            const ctx = mergeErrorContext(params.context, params.error);
+            emit("ERROR", params.category, params.event, ctx);
+        },
+        start(event, context) {
+            if (isProd()) {
+                emitProd("INFO", "infra", event, context);
+            }
+            else {
+                const ctx = context && Object.keys(context).length > 0
+                    ? ` ${JSON.stringify(context)}`
+                    : "";
+                console.log(`🚀 ${event}${ctx}`);
+            }
+        },
+        success(event, context) {
+            if (isProd()) {
+                emitProd("INFO", "infra", event, context);
+            }
+            else {
+                const ctx = context && Object.keys(context).length > 0
+                    ? ` ${JSON.stringify(context)}`
+                    : "";
+                console.log(`✅ ${event}${ctx}`);
+            }
+        },
+        failure(event, context) {
+            if (isProd()) {
+                emitProd("ERROR", "infra", event, context);
+            }
+            else {
+                const ctx = context && Object.keys(context).length > 0
+                    ? ` ${JSON.stringify(context)}`
+                    : "";
+                console.error(`❌ ${event}${ctx}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/response.d.ts

@@ -0,0 +1,28 @@
+import type { ZodIssue } from "zod";
+declare const VERSION: "v1";
+export type SuccessEnvelope<T> = {
+    data: T;
+    meta: {
+        version: typeof VERSION;
+        count?: number;
+    } & Record<string, unknown>;
+};
+export type ErrorEnvelope = {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export declare function success<T>(data: T, meta?: Record<string, unknown>): SuccessEnvelope<T>;
+export declare function successList<T>(data: T[], meta?: Record<string, unknown>): SuccessEnvelope<T[]>;
+export declare function error(code: string, message: string): ErrorEnvelope;
+export declare const CommonErrors: {
+    unauthorized(): ErrorEnvelope;
+    forbidden(): ErrorEnvelope;
+    notFound(resource?: string): ErrorEnvelope;
+    badRequest(message: string): ErrorEnvelope;
+    internalError(message?: string): ErrorEnvelope;
+    validationError(issues: ZodIssue[]): ErrorEnvelope;
+};
+export {};
+//# sourceMappingURL=response.d.ts.map

package/dist/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,QAAA,MAAM,OAAO,EAAG,IAAa,CAAC;AAE9B,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,IAAI,EAAE,CAAC,CAAC;IACR,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C,CAAC;AAEF,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAKtF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,CAAC,CAAC,EAAE,CAAC,CAKtB;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAElE;AAED,eAAO,MAAM,YAAY;oBACP,aAAa;iBAGhB,aAAa;wBAGN,MAAM,GAAG,aAAa;wBAGtB,MAAM,GAAG,aAAa;qCAGQ,aAAa;4BAGvC,QAAQ,EAAE,GAAG,aAAa;CAInD,CAAC"}

package/dist/response.js

@@ -0,0 +1,38 @@
+const VERSION = "v1";
+export function success(data, meta) {
+    return {
+        data,
+        meta: { version: VERSION, ...meta },
+    };
+}
+export function successList(data, meta) {
+    return {
+        data,
+        meta: { version: VERSION, count: data.length, ...meta },
+    };
+}
+export function error(code, message) {
+    return { error: { code, message } };
+}
+export const CommonErrors = {
+    unauthorized() {
+        return error("UNAUTHORIZED", "Authentication required");
+    },
+    forbidden() {
+        return error("FORBIDDEN", "Admin access required");
+    },
+    notFound(resource) {
+        return error("NOT_FOUND", resource ? `${resource} not found` : "Not found");
+    },
+    badRequest(message) {
+        return error("BAD_REQUEST", message);
+    },
+    internalError(message = "Internal server error") {
+        return error("INTERNAL", message);
+    },
+    validationError(issues) {
+        const message = issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+        return error("VALIDATION_ERROR", message || "Validation failed");
+    },
+};
+//# sourceMappingURL=response.js.map

package/dist/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GAAG,IAAa,CAAC;AAW9B,MAAM,UAAU,OAAO,CAAI,IAAO,EAAE,IAA8B;IAChE,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,IAAS,EACT,IAA8B;IAE9B,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,EAAE;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,IAAY,EAAE,OAAe;IACjD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,YAAY;QACV,OAAO,KAAK,CAAC,cAAc,EAAE,yBAAyB,CAAC,CAAC;IAC1D,CAAC;IACD,SAAS;QACP,OAAO,KAAK,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;IACrD,CAAC;IACD,QAAQ,CAAC,QAAiB;QACxB,OAAO,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IAC9E,CAAC;IACD,UAAU,CAAC,OAAe;QACxB,OAAO,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,aAAa,CAAC,OAAO,GAAG,uBAAuB;QAC7C,OAAO,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,eAAe,CAAC,MAAkB;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClF,OAAO,KAAK,CAAC,kBAAkB,EAAE,OAAO,IAAI,mBAAmB,CAAC,CAAC;IACnE,CAAC;CACF,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const UserRoleSchema: z.ZodEnum<["user", "admin"]>;
+export type UserRole = z.infer<typeof UserRoleSchema>;
+export declare const PaginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+}, {
+    page?: number | undefined;
+    limit?: number | undefined;
+}>;
+export type Pagination = z.infer<typeof PaginationSchema>;
+export declare const IdParamSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export type IdParam = z.infer<typeof IdParamSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc,8BAA4B,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;;;;;;EAG3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,aAAa;;;;;;EAExB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export const UserRoleSchema = z.enum(["user", "admin"]);
+export const PaginationSchema = z.object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export const IdParamSchema = z.object({
+    id: z.string().min(1),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGxD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3D,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "common-typescript-utils",
+  "version": "1.0.1",
+  "packageManager": "pnpm@9.0.0",
+  "description": "Shared TypeScript utilities for the MiniAppPolis ecosystem.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mini-app-polis/common-typescript-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mini-app-polis/common-typescript-utils/issues"
+  },
+  "homepage": "https://github.com/mini-app-polis/common-typescript-utils#readme",
+  "keywords": [
+    "typescript",
+    "utils",
+    "miniapppolis"
+  ],
+  "author": "Kaiano Levine",
+  "license": "ISC",
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.16.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.8",
+    "eslint": "^9.16.0",
+    "semantic-release": "^24.2.9",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.8"
+  }
+}