takos-common 1.0.0

package/dist/abort.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Abort Signal Utilities
+ *
+ * Shared helpers for working with AbortSignal across Takos services.
+ */
+/**
+ * Throws an `AppError` if the given signal has been aborted.
+ *
+ * @param signal  - The abort signal to check (no-op if `undefined`).
+ * @param context - A short label describing the call-site, appended to the
+ *                  error message for easier debugging (e.g. `'langgraph-start'`).
+ */
+export declare function throwIfAborted(signal: AbortSignal | undefined, context?: string): void;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CActF"}

package/dist/abort.js

@@ -0,0 +1,26 @@
+/**
+ * Abort Signal Utilities
+ *
+ * Shared helpers for working with AbortSignal across Takos services.
+ */
+import { AppError } from './errors.js';
+/**
+ * Throws an `AppError` if the given signal has been aborted.
+ *
+ * @param signal  - The abort signal to check (no-op if `undefined`).
+ * @param context - A short label describing the call-site, appended to the
+ *                  error message for easier debugging (e.g. `'langgraph-start'`).
+ */
+export function throwIfAborted(signal, context) {
+    if (!signal?.aborted) {
+        return;
+    }
+    const reason = signal.reason;
+    const message = reason instanceof Error
+        ? reason.message
+        : typeof reason === 'string'
+            ? reason
+            : 'Run aborted';
+    throw new AppError(context ? `${message} (${context})` : message);
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAA+B,EAAE,OAAgB;IAC9E,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,OAAO,GACX,MAAM,YAAY,KAAK;QACrB,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,OAAO,MAAM,KAAK,QAAQ;YAC1B,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,aAAa,CAAC;IAEtB,MAAM,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACpE,CAAC"}

package/dist/env-parse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Environment variable parsing helpers.
+ *
+ * Provides a consistent pattern across all services:
+ *  - **Required** vars (`parseIntEnvRequired`): throw if missing or invalid.
+ *  - **Optional** vars (`parseIntEnv`, `parseFloatEnv`): log a warning when the
+ *    raw value is present but invalid, then fall back to the default.
+ *
+ * The helpers intentionally avoid importing a specific logger so they stay
+ * dependency-free.  A `warnFn` callback is accepted for warning output;
+ * callers can wire it to their own logger or leave it as `console.warn`.
+ */
+type WarnFn = (message: string) => void;
+/**
+ * Parse an optional integer environment variable.
+ *
+ * - Missing / empty value -> returns `defaultValue`.
+ * - Present but not a valid integer -> logs a warning, returns `defaultValue`.
+ * - `min` / `max` constraints are enforced when provided.
+ */
+export declare function parseIntEnv(name: string, defaultValue: number, options?: {
+    min?: number;
+    max?: number;
+    warn?: WarnFn;
+}): number;
+/**
+ * Parse a required integer environment variable.
+ *
+ * - Missing / empty -> throws.
+ * - Present but not a valid integer -> throws.
+ */
+export declare function parseIntEnvRequired(name: string, options?: {
+    min?: number;
+    max?: number;
+}): number;
+/**
+ * Parse an integer from a raw string value (not directly from process.env).
+ *
+ * Useful when the env value has already been read (e.g. from a Cloudflare
+ * Workers `Env` binding) rather than from `process.env`.
+ *
+ * - `undefined` / empty -> returns `defaultValue`.
+ * - Present but not a valid integer -> logs a warning, returns `defaultValue`.
+ */
+export declare function parseIntValue(name: string, raw: string | undefined, defaultValue: number, options?: {
+    min?: number;
+    max?: number;
+    warn?: WarnFn;
+}): number;
+/**
+ * Parse an optional float environment variable.
+ *
+ * - Missing / empty value -> returns `defaultValue`.
+ * - Present but not a valid number -> logs a warning, returns `defaultValue`.
+ * - `min` / `max` constraints are enforced when provided.
+ */
+export declare function parseFloatEnv(name: string, defaultValue: number, options?: {
+    min?: number;
+    max?: number;
+    warn?: WarnFn;
+}): number;
+/**
+ * Parse a float from a raw string value (not directly from process.env).
+ *
+ * - `undefined` / empty -> returns `defaultValue`.
+ * - Present but not a valid number -> logs a warning, returns `defaultValue`.
+ */
+export declare function parseFloatValue(name: string, raw: string | undefined, defaultValue: number, options?: {
+    min?: number;
+    max?: number;
+    warn?: WarnFn;
+}): number;
+export {};
+//# sourceMappingURL=env-parse.d.ts.map

package/dist/env-parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-parse.d.ts","sourceRoot":"","sources":["../src/env-parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAOxC;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,CAoBR;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,CAoBR"}

package/dist/env-parse.js

@@ -0,0 +1,124 @@
+/**
+ * Environment variable parsing helpers.
+ *
+ * Provides a consistent pattern across all services:
+ *  - **Required** vars (`parseIntEnvRequired`): throw if missing or invalid.
+ *  - **Optional** vars (`parseIntEnv`, `parseFloatEnv`): log a warning when the
+ *    raw value is present but invalid, then fall back to the default.
+ *
+ * The helpers intentionally avoid importing a specific logger so they stay
+ * dependency-free.  A `warnFn` callback is accepted for warning output;
+ * callers can wire it to their own logger or leave it as `console.warn`.
+ */
+const defaultWarn = (msg) => console.warn(msg);
+// ---------------------------------------------------------------------------
+// Integer helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse an optional integer environment variable.
+ *
+ * - Missing / empty value -> returns `defaultValue`.
+ * - Present but not a valid integer -> logs a warning, returns `defaultValue`.
+ * - `min` / `max` constraints are enforced when provided.
+ */
+export function parseIntEnv(name, defaultValue, options) {
+    const raw = (typeof globalThis.process !== 'undefined' ? process.env[name] : undefined)?.trim();
+    if (!raw)
+        return defaultValue;
+    return parseIntValue(name, raw, defaultValue, options);
+}
+/**
+ * Parse a required integer environment variable.
+ *
+ * - Missing / empty -> throws.
+ * - Present but not a valid integer -> throws.
+ */
+export function parseIntEnvRequired(name, options) {
+    const raw = (typeof globalThis.process !== 'undefined' ? process.env[name] : undefined)?.trim();
+    if (!raw) {
+        throw new Error(`Required environment variable ${name} is not set`);
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid integer for environment variable ${name}: ${raw}`);
+    }
+    if (options?.min != null && parsed < options.min) {
+        throw new Error(`Environment variable ${name} value ${parsed} is below minimum ${options.min}`);
+    }
+    if (options?.max != null && parsed > options.max) {
+        throw new Error(`Environment variable ${name} value ${parsed} exceeds maximum ${options.max}`);
+    }
+    return parsed;
+}
+/**
+ * Parse an integer from a raw string value (not directly from process.env).
+ *
+ * Useful when the env value has already been read (e.g. from a Cloudflare
+ * Workers `Env` binding) rather than from `process.env`.
+ *
+ * - `undefined` / empty -> returns `defaultValue`.
+ * - Present but not a valid integer -> logs a warning, returns `defaultValue`.
+ */
+export function parseIntValue(name, raw, defaultValue, options) {
+    const warn = options?.warn ?? defaultWarn;
+    if (!raw || raw.trim() === '')
+        return defaultValue;
+    const trimmed = raw.trim();
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed)) {
+        warn(`Invalid integer for ${name}: "${trimmed}", using default ${defaultValue}`);
+        return defaultValue;
+    }
+    if (options?.min != null && parsed < options.min) {
+        warn(`Value for ${name} (${parsed}) is below minimum ${options.min}, using default ${defaultValue}`);
+        return defaultValue;
+    }
+    if (options?.max != null && parsed > options.max) {
+        warn(`Value for ${name} (${parsed}) exceeds maximum ${options.max}, using default ${defaultValue}`);
+        return defaultValue;
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Float helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse an optional float environment variable.
+ *
+ * - Missing / empty value -> returns `defaultValue`.
+ * - Present but not a valid number -> logs a warning, returns `defaultValue`.
+ * - `min` / `max` constraints are enforced when provided.
+ */
+export function parseFloatEnv(name, defaultValue, options) {
+    const raw = (typeof globalThis.process !== 'undefined' ? process.env[name] : undefined)?.trim();
+    if (!raw)
+        return defaultValue;
+    return parseFloatValue(name, raw, defaultValue, options);
+}
+/**
+ * Parse a float from a raw string value (not directly from process.env).
+ *
+ * - `undefined` / empty -> returns `defaultValue`.
+ * - Present but not a valid number -> logs a warning, returns `defaultValue`.
+ */
+export function parseFloatValue(name, raw, defaultValue, options) {
+    const warn = options?.warn ?? defaultWarn;
+    if (!raw || raw.trim() === '')
+        return defaultValue;
+    const trimmed = raw.trim();
+    const parsed = Number.parseFloat(trimmed);
+    if (!Number.isFinite(parsed)) {
+        warn(`Invalid number for ${name}: "${trimmed}", using default ${defaultValue}`);
+        return defaultValue;
+    }
+    if (options?.min != null && parsed < options.min) {
+        warn(`Value for ${name} (${parsed}) is below minimum ${options.min}, using default ${defaultValue}`);
+        return defaultValue;
+    }
+    if (options?.max != null && parsed > options.max) {
+        warn(`Value for ${name} (${parsed}) exceeds maximum ${options.max}, using default ${defaultValue}`);
+        return defaultValue;
+    }
+    return parsed;
+}
+//# sourceMappingURL=env-parse.js.map

package/dist/env-parse.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Standardized Error Handling for Takos Platform
+ *
+ * This module provides a consistent error handling pattern across all takos packages.
+ * All errors extend from AppError and include:
+ * - code: A unique error code for client-side handling
+ * - message: A user-safe message (no internal details)
+ * - statusCode: The HTTP status code to return
+ * - details: Optional field-level or additional details
+ */
+import type { Logger } from './logger.js';
+/**
+ * Standard error codes for consistent client handling
+ */
+export declare const ErrorCodes: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly GONE: "GONE";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly BAD_GATEWAY: "BAD_GATEWAY";
+    readonly GATEWAY_TIMEOUT: "GATEWAY_TIMEOUT";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Standard error response format for API responses
+ */
+export interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Field-level validation error details
+ */
+export interface ValidationErrorDetail {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+/**
+ * Base application error class
+ * All custom errors should extend from this class
+ */
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(message: string, code?: ErrorCode, statusCode?: number, details?: unknown);
+    /**
+     * Convert error to API response format
+     * This ensures no internal details leak to clients
+     */
+    toResponse(): ErrorResponse;
+}
+/**
+ * 400 Bad Request - Invalid request syntax or parameters
+ */
+export declare class BadRequestError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 401 Unauthorized - Authentication required or invalid
+ */
+export declare class AuthenticationError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 402 Payment Required - Payment is required to access the resource
+ */
+export declare class PaymentRequiredError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 403 Forbidden - Authenticated but not authorized
+ */
+export declare class AuthorizationError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 404 Not Found - Resource does not exist
+ */
+export declare class NotFoundError extends AppError {
+    constructor(resource?: string, details?: unknown);
+}
+/**
+ * 409 Conflict - Resource conflict (e.g., duplicate)
+ */
+export declare class ConflictError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 410 Gone - Resource no longer available
+ */
+export declare class GoneError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 413 Payload Too Large - Request payload exceeds limit
+ */
+export declare class PayloadTooLargeError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 422 Unprocessable Entity - Validation failed
+ */
+export declare class ValidationError extends AppError {
+    readonly fieldErrors: ValidationErrorDetail[];
+    constructor(message?: string, fieldErrors?: ValidationErrorDetail[]);
+}
+/**
+ * 429 Too Many Requests - Rate limit exceeded
+ */
+export declare class RateLimitError extends AppError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * 500 Internal Server Error - Unexpected server error
+ */
+export declare class InternalError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 501 Not Implemented - Functionality not implemented
+ */
+export declare class NotImplementedError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 502 Bad Gateway - Invalid response from upstream service
+ */
+export declare class BadGatewayError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 503 Service Unavailable - Service temporarily unavailable
+ */
+export declare class ServiceUnavailableError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * 504 Gateway Timeout - Upstream service timeout
+ */
+export declare class GatewayTimeoutError extends AppError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Type guard to check if an error is an AppError
+ */
+export declare function isAppError(error: unknown): error is AppError;
+/**
+ * Convert unknown error to AppError
+ * Use this to normalize errors before sending responses
+ */
+export declare function normalizeError(error: unknown, logger?: Logger): AppError;
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * When called with a single argument the behaviour matches the former
+ * `runtime-service/utils/error-message` helper (`String(err)` for
+ * non-Error values).  When a `fallback` string is supplied the
+ * behaviour matches the former `control/web/lib/errors` helper
+ * (returns the fallback when no meaningful message can be extracted).
+ */
+export declare function getErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * Log error with full details for server-side debugging
+ */
+export declare function logError(error: unknown, context?: Record<string, unknown>, logger?: Logger): void;
+//# 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":"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"}