@defai.digital/contracts 13.0.3

package/dist/provider/v1/port.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Provider Port - Interface for LLM Provider Access
+ *
+ * This defines the contract that provider adapters implement.
+ * Application layers (CLI, MCP Server) should depend on these interfaces,
+ * not on the concrete adapter implementations.
+ *
+ * Following Ports & Adapters (Hexagonal Architecture) pattern.
+ */
+import { z } from 'zod';
+/**
+ * Message in a provider request
+ */
+export declare const ProviderMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<["system", "user", "assistant"]>;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: "system" | "user" | "assistant";
+    content: string;
+}, {
+    role: "system" | "user" | "assistant";
+    content: string;
+}>;
+/**
+ * Provider request schema
+ */
+export declare const ProviderRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    model: z.ZodString;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["system", "user", "assistant"]>;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }, {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>, "many">;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requestId: string;
+    messages: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+    model: string;
+    maxTokens?: number | undefined;
+    systemPrompt?: string | undefined;
+    temperature?: number | undefined;
+}, {
+    requestId: string;
+    messages: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[];
+    model: string;
+    maxTokens?: number | undefined;
+    systemPrompt?: string | undefined;
+    temperature?: number | undefined;
+}>;
+/**
+ * Provider response schema
+ */
+export declare const ProviderResponseSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    success: z.ZodBoolean;
+    content: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+    }, {
+        code: string;
+        message: string;
+    }>>;
+    usage: z.ZodOptional<z.ZodObject<{
+        promptTokens: z.ZodNumber;
+        completionTokens: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        promptTokens: number;
+        completionTokens: number;
+    }, {
+        promptTokens: number;
+        completionTokens: number;
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    finishReason: z.ZodOptional<z.ZodEnum<["stop", "length", "error"]>>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    requestId: string;
+    error?: {
+        code: string;
+        message: string;
+    } | undefined;
+    content?: string | undefined;
+    model?: string | undefined;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    } | undefined;
+    finishReason?: "length" | "error" | "stop" | undefined;
+}, {
+    success: boolean;
+    requestId: string;
+    error?: {
+        code: string;
+        message: string;
+    } | undefined;
+    content?: string | undefined;
+    model?: string | undefined;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    } | undefined;
+    finishReason?: "length" | "error" | "stop" | undefined;
+}>;
+/**
+ * Model info schema
+ */
+export declare const ModelInfoSchema: z.ZodObject<{
+    modelId: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    contextLength: z.ZodOptional<z.ZodNumber>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    modelId: string;
+    displayName?: string | undefined;
+    capabilities?: string[] | undefined;
+    contextLength?: number | undefined;
+    isDefault?: boolean | undefined;
+}, {
+    modelId: string;
+    displayName?: string | undefined;
+    capabilities?: string[] | undefined;
+    contextLength?: number | undefined;
+    isDefault?: boolean | undefined;
+}>;
+export type ProviderMessage = z.infer<typeof ProviderMessageSchema>;
+export type ProviderRequest = z.infer<typeof ProviderRequestSchema>;
+export type ProviderResponse = z.infer<typeof ProviderResponseSchema>;
+export type ModelInfo = z.infer<typeof ModelInfoSchema>;
+/**
+ * Provider Port Interface
+ *
+ * INV-PROV-PORT-001: Implementations must validate requests before execution
+ * INV-PROV-PORT-002: Responses must match ProviderResponseSchema
+ * INV-PROV-PORT-003: Errors must not throw; return error response instead
+ */
+export interface ProviderPort {
+    /**
+     * Provider identifier
+     */
+    readonly providerId: string;
+    /**
+     * Complete a request
+     * INV-PROV-PORT-003: Must not throw; returns error in response
+     */
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * Check if provider is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get available models
+     */
+    getModels(): ModelInfo[];
+    /**
+     * Get provider status (open, closed, half-open for circuit breaker)
+     */
+    getStatus(): 'open' | 'closed' | 'half-open';
+}
+/**
+ * Provider Registry Port Interface
+ *
+ * INV-PROV-REG-001: getProvider returns undefined for unknown providers
+ * INV-PROV-REG-002: listProviders returns deterministic order
+ */
+export interface ProviderRegistryPort {
+    /**
+     * Get a provider by ID
+     * Returns undefined if not found (INV-PROV-REG-001)
+     */
+    getProvider(providerId: string): ProviderPort | undefined;
+    /**
+     * Get the default provider
+     */
+    getDefaultProvider(): ProviderPort | undefined;
+    /**
+     * List all provider IDs
+     * Returns deterministic order (INV-PROV-REG-002)
+     */
+    listProviders(): string[];
+    /**
+     * Check if a provider exists
+     */
+    hasProvider(providerId: string): boolean;
+}
+/**
+ * Validate a provider request
+ */
+export declare function validateProviderRequest(data: unknown): ProviderRequest;
+/**
+ * Validate a provider response
+ */
+export declare function validateProviderResponse(data: unknown): ProviderResponse;
+/**
+ * Safe validation for provider request
+ */
+export declare function safeValidateProviderRequest(data: unknown): {
+    success: true;
+    data: ProviderRequest;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Create a success response
+ */
+export declare function createProviderSuccessResponse(requestId: string, content: string, options?: {
+    model?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    finishReason?: 'stop' | 'length';
+}): ProviderResponse;
+/**
+ * Create an error response
+ */
+export declare function createProviderErrorResponse(requestId: string, code: string, message: string): ProviderResponse;
+//# sourceMappingURL=port.d.ts.map

package/dist/provider/v1/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/provider/v1/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;EAGhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkBjC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;EAM1B,CAAC;AAMH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE9D;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,SAAS,EAAE,CAAC;IAEzB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAE1D;;OAEG;IACH,kBAAkB,IAAI,YAAY,GAAG,SAAS,CAAC;IAE/C;;;OAGG;IACH,aAAa,IAAI,MAAM,EAAE,CAAC;IAE1B;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1C;AAMD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAEtE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,CAExE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,OAAO,GAAG;IAC1D,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,eAAe,CAAC;CACvB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;CAAE,CAMxC;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAClC,GACA,gBAAgB,CASlB;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,gBAAgB,CAOlB"}

package/dist/provider/v1/port.js

@@ -0,0 +1,113 @@
+/**
+ * Provider Port - Interface for LLM Provider Access
+ *
+ * This defines the contract that provider adapters implement.
+ * Application layers (CLI, MCP Server) should depend on these interfaces,
+ * not on the concrete adapter implementations.
+ *
+ * Following Ports & Adapters (Hexagonal Architecture) pattern.
+ */
+import { z } from 'zod';
+// ============================================================================
+// Provider Request/Response Schemas
+// ============================================================================
+/**
+ * Message in a provider request
+ */
+export const ProviderMessageSchema = z.object({
+    role: z.enum(['system', 'user', 'assistant']),
+    content: z.string(),
+});
+/**
+ * Provider request schema
+ */
+export const ProviderRequestSchema = z.object({
+    requestId: z.string().uuid(),
+    model: z.string().min(1),
+    messages: z.array(ProviderMessageSchema).min(1),
+    maxTokens: z.number().int().positive().optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    systemPrompt: z.string().optional(),
+});
+/**
+ * Provider response schema
+ */
+export const ProviderResponseSchema = z.object({
+    requestId: z.string().uuid(),
+    success: z.boolean(),
+    content: z.string().optional(),
+    error: z
+        .object({
+        code: z.string(),
+        message: z.string(),
+    })
+        .optional(),
+    usage: z
+        .object({
+        promptTokens: z.number().int().nonnegative(),
+        completionTokens: z.number().int().nonnegative(),
+    })
+        .optional(),
+    model: z.string().optional(),
+    finishReason: z.enum(['stop', 'length', 'error']).optional(),
+});
+/**
+ * Model info schema
+ */
+export const ModelInfoSchema = z.object({
+    modelId: z.string().min(1),
+    displayName: z.string().optional(),
+    contextLength: z.number().int().positive().optional(),
+    isDefault: z.boolean().optional(),
+    capabilities: z.array(z.string()).optional(),
+});
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Validate a provider request
+ */
+export function validateProviderRequest(data) {
+    return ProviderRequestSchema.parse(data);
+}
+/**
+ * Validate a provider response
+ */
+export function validateProviderResponse(data) {
+    return ProviderResponseSchema.parse(data);
+}
+/**
+ * Safe validation for provider request
+ */
+export function safeValidateProviderRequest(data) {
+    const result = ProviderRequestSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}
+/**
+ * Create a success response
+ */
+export function createProviderSuccessResponse(requestId, content, options) {
+    return {
+        requestId,
+        success: true,
+        content,
+        model: options?.model,
+        usage: options?.usage,
+        finishReason: options?.finishReason ?? 'stop',
+    };
+}
+/**
+ * Create an error response
+ */
+export function createProviderErrorResponse(requestId, code, message) {
+    return {
+        requestId,
+        success: false,
+        error: { code, message },
+        finishReason: 'error',
+    };
+}
+//# sourceMappingURL=port.js.map

package/dist/provider/v1/port.js.map

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

package/dist/provider/v1/rate-limit.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Rate Limit Contract V1
+ *
+ * Provides rate limiting for provider requests using token bucket algorithm.
+ * Prevents overwhelming providers with too many requests.
+ *
+ * Invariants:
+ * - INV-RL-001: Tokens never exceed burst capacity
+ * - INV-RL-002: Tokens refill at configured rate
+ * - INV-RL-003: Strategy (reject/queue/backoff) honored
+ * - INV-RL-004: Queue never exceeds maxQueueSize
+ */
+import { z } from 'zod';
+/**
+ * Rate limit strategy when limit is reached
+ */
+export declare const RateLimitStrategySchema: z.ZodEnum<["reject", "queue", "backoff"]>;
+export type RateLimitStrategy = z.infer<typeof RateLimitStrategySchema>;
+/**
+ * Rate limit state
+ */
+export declare const RateLimitStateEnumSchema: z.ZodEnum<["normal", "throttled", "blocked"]>;
+export type RateLimitStateEnum = z.infer<typeof RateLimitStateEnumSchema>;
+/**
+ * Rate limit configuration
+ */
+export declare const RateLimitConfigSchema: z.ZodObject<{
+    /** Requests per minute per provider */
+    requestsPerMinute: z.ZodDefault<z.ZodNumber>;
+    /** Tokens per minute per provider */
+    tokensPerMinute: z.ZodDefault<z.ZodNumber>;
+    /** Burst allowance multiplier (INV-RL-001) */
+    burstMultiplier: z.ZodDefault<z.ZodNumber>;
+    /** Strategy when limit reached (INV-RL-003) */
+    strategy: z.ZodDefault<z.ZodEnum<["reject", "queue", "backoff"]>>;
+    /** Max queue size if strategy is 'queue' (INV-RL-004) */
+    maxQueueSize: z.ZodDefault<z.ZodNumber>;
+    /** Backoff base delay in ms */
+    backoffBaseMs: z.ZodDefault<z.ZodNumber>;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier: z.ZodDefault<z.ZodNumber>;
+    /** Maximum backoff delay in ms */
+    maxBackoffMs: z.ZodDefault<z.ZodNumber>;
+    /** Enable token-based rate limiting */
+    enableTokenLimit: z.ZodDefault<z.ZodBoolean>;
+    /** Enable request-based rate limiting */
+    enableRequestLimit: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    backoffMultiplier: number;
+    requestsPerMinute: number;
+    tokensPerMinute: number;
+    burstMultiplier: number;
+    strategy: "queue" | "reject" | "backoff";
+    maxQueueSize: number;
+    backoffBaseMs: number;
+    maxBackoffMs: number;
+    enableTokenLimit: boolean;
+    enableRequestLimit: boolean;
+}, {
+    backoffMultiplier?: number | undefined;
+    requestsPerMinute?: number | undefined;
+    tokensPerMinute?: number | undefined;
+    burstMultiplier?: number | undefined;
+    strategy?: "queue" | "reject" | "backoff" | undefined;
+    maxQueueSize?: number | undefined;
+    backoffBaseMs?: number | undefined;
+    maxBackoffMs?: number | undefined;
+    enableTokenLimit?: boolean | undefined;
+    enableRequestLimit?: boolean | undefined;
+}>;
+export type RateLimitConfig = z.infer<typeof RateLimitConfigSchema>;
+/**
+ * Rate limit state snapshot
+ */
+export declare const RateLimitStateSchema: z.ZodObject<{
+    /** Current available request tokens */
+    requestTokens: z.ZodNumber;
+    /** Current available output tokens */
+    outputTokens: z.ZodNumber;
+    /** Requests in current window */
+    requestCount: z.ZodNumber;
+    /** Tokens used in current window */
+    tokenCount: z.ZodNumber;
+    /** Start of current rate limit window */
+    windowStart: z.ZodString;
+    /** Current queue size */
+    queueSize: z.ZodNumber;
+    /** Next allowed request time (if rate limited) */
+    nextAllowedTime: z.ZodOptional<z.ZodString>;
+    /** Current state */
+    state: z.ZodEnum<["normal", "throttled", "blocked"]>;
+    /** Last refill timestamp */
+    lastRefillTime: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tokenCount: number;
+    requestCount: number;
+    windowStart: string;
+    state: "blocked" | "normal" | "throttled";
+    requestTokens: number;
+    outputTokens: number;
+    queueSize: number;
+    lastRefillTime: string;
+    nextAllowedTime?: string | undefined;
+}, {
+    tokenCount: number;
+    requestCount: number;
+    windowStart: string;
+    state: "blocked" | "normal" | "throttled";
+    requestTokens: number;
+    outputTokens: number;
+    queueSize: number;
+    lastRefillTime: string;
+    nextAllowedTime?: string | undefined;
+}>;
+export type RateLimitState = z.infer<typeof RateLimitStateSchema>;
+/**
+ * Rate limit result
+ */
+export declare const RateLimitResultSchema: z.ZodObject<{
+    /** Whether request is allowed */
+    allowed: z.ZodBoolean;
+    /** Wait time in ms (for backoff strategy) */
+    waitMs: z.ZodNumber;
+    /** Whether request was queued */
+    queued: z.ZodOptional<z.ZodBoolean>;
+    /** Queue position if queued */
+    queuePosition: z.ZodOptional<z.ZodNumber>;
+    /** Error code if rejected */
+    error: z.ZodOptional<z.ZodString>;
+    /** Remaining requests in window */
+    remainingRequests: z.ZodOptional<z.ZodNumber>;
+    /** Remaining tokens in window */
+    remainingTokens: z.ZodOptional<z.ZodNumber>;
+    /** Time until rate limit resets */
+    resetInMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    allowed: boolean;
+    waitMs: number;
+    error?: string | undefined;
+    queued?: boolean | undefined;
+    queuePosition?: number | undefined;
+    remainingRequests?: number | undefined;
+    remainingTokens?: number | undefined;
+    resetInMs?: number | undefined;
+}, {
+    allowed: boolean;
+    waitMs: number;
+    error?: string | undefined;
+    queued?: boolean | undefined;
+    queuePosition?: number | undefined;
+    remainingRequests?: number | undefined;
+    remainingTokens?: number | undefined;
+    resetInMs?: number | undefined;
+}>;
+export type RateLimitResult = z.infer<typeof RateLimitResultSchema>;
+/**
+ * Rate limit event types
+ */
+export declare const RateLimitEventTypeSchema: z.ZodEnum<["rateLimit.acquired", "rateLimit.rejected", "rateLimit.queued", "rateLimit.dequeued", "rateLimit.refilled", "rateLimit.stateChanged"]>;
+export type RateLimitEventType = z.infer<typeof RateLimitEventTypeSchema>;
+/**
+ * Rate limit event
+ */
+export declare const RateLimitEventSchema: z.ZodObject<{
+    eventId: z.ZodString;
+    type: z.ZodEnum<["rateLimit.acquired", "rateLimit.rejected", "rateLimit.queued", "rateLimit.dequeued", "rateLimit.refilled", "rateLimit.stateChanged"]>;
+    providerId: z.ZodString;
+    timestamp: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "rateLimit.acquired" | "rateLimit.rejected" | "rateLimit.queued" | "rateLimit.dequeued" | "rateLimit.refilled" | "rateLimit.stateChanged";
+    timestamp: string;
+    eventId: string;
+    providerId: string;
+    details?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+}, {
+    type: "rateLimit.acquired" | "rateLimit.rejected" | "rateLimit.queued" | "rateLimit.dequeued" | "rateLimit.refilled" | "rateLimit.stateChanged";
+    timestamp: string;
+    eventId: string;
+    providerId: string;
+    details?: Record<string, unknown> | undefined;
+    requestId?: string | undefined;
+}>;
+export type RateLimitEvent = z.infer<typeof RateLimitEventSchema>;
+/**
+ * Error codes for rate limit operations
+ */
+export declare const RateLimitErrorCodes: {
+    readonly RATE_LIMITED: "RATE_LIMIT_EXCEEDED";
+    readonly QUEUE_FULL: "RATE_LIMIT_QUEUE_FULL";
+    readonly TOKEN_LIMIT: "RATE_LIMIT_TOKEN_EXCEEDED";
+    readonly REQUEST_LIMIT: "RATE_LIMIT_REQUEST_EXCEEDED";
+    readonly INVALID_CONFIG: "RATE_LIMIT_INVALID_CONFIG";
+};
+export type RateLimitErrorCode = (typeof RateLimitErrorCodes)[keyof typeof RateLimitErrorCodes];
+/**
+ * Validates rate limit configuration
+ */
+export declare function validateRateLimitConfig(data: unknown): RateLimitConfig;
+/**
+ * Validates rate limit state
+ */
+export declare function validateRateLimitState(data: unknown): RateLimitState;
+/**
+ * Creates default rate limit configuration
+ */
+export declare function createDefaultRateLimitConfig(): RateLimitConfig;
+/**
+ * Creates initial rate limit state
+ */
+export declare function createInitialRateLimitState(config: RateLimitConfig): RateLimitState;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/provider/v1/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/provider/v1/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,uBAAuB,2CAIlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,wBAAwB,+CAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,uCAAuC;;IAGvC,qCAAqC;;IAGrC,8CAA8C;;IAG9C,+CAA+C;;IAG/C,yDAAyD;;IAGzD,+BAA+B;;IAG/B,iDAAiD;;IAGjD,kCAAkC;;IAGlC,uCAAuC;;IAGvC,yCAAyC;;;;;;;;;;;;;;;;;;;;;;;;EAEzC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,oBAAoB;IAC/B,uCAAuC;;IAGvC,sCAAsC;;IAGtC,iCAAiC;;IAGjC,oCAAoC;;IAGpC,yCAAyC;;IAGzC,yBAAyB;;IAGzB,kDAAkD;;IAGlD,oBAAoB;;IAGpB,4BAA4B;;;;;;;;;;;;;;;;;;;;;;EAE5B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,iCAAiC;;IAGjC,6CAA6C;;IAG7C,iCAAiC;;IAGjC,+BAA+B;;IAG/B,6BAA6B;;IAG7B,mCAAmC;;IAGnC,iCAAiC;;IAGjC,mCAAmC;;;;;;;;;;;;;;;;;;;;EAEnC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,wBAAwB,mJAOnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;EAO/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAEtE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAEpE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAE9D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,CAYnF"}