@scrawn/core 0.0.2 → 0.0.6

package/README.md

@@ -0,0 +1,40 @@
+# Scrawn SDK
+
+## What is Scrawn.js?
+
+Scrawn.js is the official TypeScript SDK for integrating Scrawn's usage-based billing into your applications. It provides a simple, type-safe interface for tracking usage events and collecting payments via gRPC.
+
+[View Docs](https://scrawn.vercel.app/docs/scrawn-js)
+
+## Key Features
+
+- **Simple API** - Track usage with a single function call
+- **Type-Safe** - Full TypeScript support with auto-completion
+- **gRPC-Powered** - Built on Connect-RPC for efficient communication
+- **Framework Agnostic** - Works with any JavaScript framework
+- **Middleware Support** - Built-in middleware with whitelist/blacklist patterns
+
+## Installation
+
+Install Scrawn.js in your project:
+
+```bash
+bun add @scrawn/core
+```
+
+## Quick Example
+
+```typescript
+import { Scrawn } from "@scrawn/core";
+
+const scrawn = new Scrawn({
+  apiKey: process.env.SCRAWN_KEY as `scrn_${string}`,
+  baseURL: process.env.SCRAWN_BASE_URL || "http://localhost:8069",
+});
+
+// Track a billable event
+await scrawn.sdkCallEventConsumer({
+  userId: "user-123",
+  debitAmount: 100,
+});
+```

package/dist/config.d.ts

@@ -8,9 +8,9 @@ export declare const ScrawnConfig: {
      */
     readonly grpc: {
         /**
-         * HTTP version to use for gRPC transport.
+         * Default gRPC port
          */
-        readonly httpVersion: "1.1";
+        readonly defaultPort: 8069;
     };
     /**
      * Logging configuration
@@ -23,4 +23,19 @@ export declare const ScrawnConfig: {
     };
 };
 export type ScrawnConfig = typeof ScrawnConfig;
+/**
+ * Configuration for the Scrawn CLI (`scrawn tag sync`).
+ * Used in the project's `scrawn.config.ts` file.
+ */
+export interface ScrawnCLIConfig {
+    apiKey: string;
+    grpcUrl: string;
+    httpUrl: string;
+    directory: string;
+}
+/**
+ * Type-safe helper for defining project configuration in `scrawn.config.ts`.
+ * Returns the config unchanged — purely a type-witness.
+ */
+export declare function scrawnConfig(config: ScrawnCLIConfig): ScrawnCLIConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,YAAY;IACvB;;OAEG;;QAED;;WAEG;;;IAKL;;OAEG;;QAED;;WAEG;;;CAGG,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,YAAY;IACvB;;OAEG;;QAED;;WAEG;;;IAIL;;OAEG;;QAED;;WAEG;;;CAGG,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAErE"}

package/dist/config.js

@@ -8,9 +8,9 @@ export const ScrawnConfig = {
      */
     grpc: {
         /**
-         * HTTP version to use for gRPC transport.
+         * Default gRPC port
          */
-        httpVersion: '1.1',
+        defaultPort: 8069,
     },
     /**
      * Logging configuration
@@ -22,4 +22,11 @@ export const ScrawnConfig = {
         enableDebug: false,
     },
 };
+/**
+ * Type-safe helper for defining project configuration in `scrawn.config.ts`.
+ * Returns the config unchanged — purely a type-witness.
+ */
+export function scrawnConfig(config) {
+    return config;
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;OAEG;IACH,IAAI,EAAE;QACJ;;WAEG;QACH,WAAW,EAAE,KAAc;KAE5B;IAED;;OAEG;IACH,OAAO,EAAE;QACP;;WAEG;QACH,WAAW,EAAE,KAAK;KACnB;CACO,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B;;OAEG;IACH,IAAI,EAAE;QACJ;;WAEG;QACH,WAAW,EAAE,IAAI;KAClB;IAED;;OAEG;IACH,OAAO,EAAE;QACP;;WAEG;QACH,WAAW,EAAE,KAAK;KACnB;CACO,CAAC;AAeX;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/auth/apiKeyAuth.d.ts

@@ -1,8 +1,8 @@
-import { AuthBase } from './baseAuth.js';
-import type { Scrawn } from '../scrawn.js';
+import { AuthBase } from "./baseAuth.js";
 /**
- * API key format: sk_ followed by 16 alphanumeric characters
- * @example 'sk_abc123def456ghi7'
+ * API key format: scrn_<role>_ followed by 32 alphanumeric characters.
+ * Roles: dash (dashboard), live (production), test
+ * @example 'scrn_live_abc123def456ghi789jkl012mno345pq'
  */
 export type ApiKeyFormat = `scrn_${string}`;
 /**
@@ -33,8 +33,6 @@ export type ApiKeyAuthCreds = {
  * ```
  */
 export declare class ApiKeyAuth extends AuthBase<ApiKeyAuthCreds> {
-    /** Authentication method identifier */
-    name: "api";
     /** Validated API key */
     private validatedKey;
     /**
@@ -44,13 +42,6 @@ export declare class ApiKeyAuth extends AuthBase<ApiKeyAuthCreds> {
      * @throws Error if API key format is invalid
      */
     constructor(apiKey: string);
-    /**
-     * Initialize the API key auth method.
-     * No additional setup is required for API key authentication.
-     *
-     * @param scrawn - The Scrawn SDK instance (optional, unused)
-     */
-    init(scrawn?: Scrawn): Promise<void>;
     /**
      * Get the API key credentials.
      *

package/dist/core/auth/apiKeyAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apiKeyAuth.d.ts","sourceRoot":"","sources":["../../../src/core/auth/apiKeyAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAK3C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,MAAM,EAAE,CAAC;AAE5C;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAQxD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,QAAQ,CAAC,eAAe,CAAC;IACvD,uCAAuC;IACvC,IAAI,EAAG,KAAK,CAAU;IAEtB,wBAAwB;IACxB,OAAO,CAAC,YAAY,CAAe;IAEnC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM;IAK1B;;;;;OAKG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM;IAK1B;;;;;;;;;;OAUG;IACG,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;CAG3C"}
+{"version":3,"file":"apiKeyAuth.d.ts","sourceRoot":"","sources":["../../../src/core/auth/apiKeyAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAMzC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,MAAM,EAAE,CAAC;AAI5C;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAcxD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,UAAW,SAAQ,QAAQ,CAAC,eAAe,CAAC;IACvD,wBAAwB;IACxB,OAAO,CAAC,YAAY,CAAe;IAEnC;;;;;OAKG;gBACS,MAAM,EAAE,MAAM;IAK1B;;;;;;;;;;OAUG;IACG,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;CAG3C"}

package/dist/core/auth/apiKeyAuth.js

@@ -1,11 +1,13 @@
-import { AuthBase } from './baseAuth.js';
-import { ScrawnLogger } from '../../utils/logger.js';
-const log = new ScrawnLogger('Auth');
+import { AuthBase } from "./baseAuth.js";
+import { ScrawnLogger } from "../../utils/logger.js";
+import { ScrawnValidationError } from "../errors/index.js";
+const log = new ScrawnLogger("Auth");
+const API_KEY_REGEX = /^scrn_(dash|live|test)_[a-zA-Z0-9]{32}$/;
 /**
  * Type guard to validate API key format
  */
 export function isValidApiKey(key) {
-    return /^scrn_[a-zA-Z0-9]{32}$/.test(key);
+    return API_KEY_REGEX.test(key);
 }
 /**
  * Validates and returns a properly typed API key
@@ -14,7 +16,12 @@ export function isValidApiKey(key) {
 export function validateApiKey(key) {
     if (!isValidApiKey(key)) {
         log.error(`Invalid API key format: "${key}".`);
-        throw new Error(`Invalid API key format. Expected format: sk_<16 alphanumeric characters>. Got: ${key.substring(0, 10)}...`);
+        throw new ScrawnValidationError("Invalid API key format. Expected format: scrn_<dash|live|test>_<32 alphanumeric characters>", {
+            details: {
+                providedKey: key.substring(0, 14) + "...",
+                expectedFormat: "scrn_<role>_<32 alphanumeric characters>",
+            },
+        });
     }
     return key;
 }
@@ -39,20 +46,8 @@ export class ApiKeyAuth extends AuthBase {
      */
     constructor(apiKey) {
         super();
-        /** Authentication method identifier */
-        this.name = 'api';
         this.validatedKey = validateApiKey(apiKey);
     }
-    /**
-     * Initialize the API key auth method.
-     * No additional setup is required for API key authentication.
-     *
-     * @param scrawn - The Scrawn SDK instance (optional, unused)
-     */
-    async init(scrawn) {
-        // nothing extra for now
-        return;
-    }
     /**
      * Get the API key credentials.
      *

package/dist/core/auth/apiKeyAuth.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiKeyAuth.js","sourceRoot":"","sources":["../../../src/core/auth/apiKeyAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;AAQrC;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,kFAAkF,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAyB;IAOvD;;;;;OAKG;IACH,YAAY,MAAc;QACxB,KAAK,EAAE,CAAC;QAbV,uCAAuC;QACvC,SAAI,GAAG,KAAc,CAAC;QAapB,IAAI,CAAC,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,MAAe;QACxB,wBAAwB;QACxB,OAAO;IACT,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"apiKeyAuth.js","sourceRoot":"","sources":["../../../src/core/auth/apiKeyAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;AASrC,MAAM,aAAa,GAAG,yCAAyC,CAAC;AAEhE;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,KAAK,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAAC;QAC/C,MAAM,IAAI,qBAAqB,CAC7B,6FAA6F,EAC7F;YACE,OAAO,EAAE;gBACP,WAAW,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK;gBACzC,cAAc,EAAE,0CAA0C;aAC3D;SACF,CACF,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AASD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,UAAW,SAAQ,QAAyB;IAIvD;;;;;OAKG;IACH,YAAY,MAAc;QACxB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACvC,CAAC;CACF"}

package/dist/core/auth/baseAuth.d.ts

@@ -1,4 +1,3 @@
-import type { Scrawn } from '../scrawn.js';
 /**
  * Abstract base class for authentication methods.
  *
@@ -12,12 +11,6 @@ import type { Scrawn } from '../scrawn.js';
  * type MyAuthCreds = { token: string };
  *
  * export class MyAuth extends AuthBase<MyAuthCreds> {
- *   name = 'my_auth';
- *
- *   async init(scrawn: Scrawn) {
- *     // Setup logic here
- *   }
- *
  *   async getCreds(): Promise<MyAuthCreds> {
  *     return { token: 'my_token' };
  *   }
@@ -25,21 +18,6 @@ import type { Scrawn } from '../scrawn.js';
  * ```
  */
 export declare abstract class AuthBase<TCreds = unknown> {
-    /**
-     * Unique identifier for this authentication method.
-     * Used to register and reference the auth method (e.g., 'api', 'oauth').
-     */
-    abstract name: string;
-    /**
-     * Initialize the authentication method.
-     *
-     * Called once during SDK setup. Use this to perform any necessary
-     * initialization like token validation or refresh.
-     *
-     * @param scrawn - The Scrawn SDK instance
-     * @returns A promise that resolves when initialization is complete
-     */
-    abstract init(scrawn: Scrawn): Promise<void>;
     /**
      * Retrieve the current credentials for this authentication method.
      *
@@ -73,20 +51,20 @@ export declare abstract class AuthBase<TCreds = unknown> {
      */
     preRun?(): Promise<void>;
     /**
-      * Optional hook that runs after each event is processed.
-      *
-      * Use this for cleanup operations or logging that should happen
-      * after every request completes.
-      *
-      * @returns A promise that resolves when the post-run hook completes
-      *
-      * @example
-      * ```typescript
-      * async postRun() {
-      *   await this.logRequestMetrics();
-      * }
-      * ```
-      */
+     * Optional hook that runs after each event is processed.
+     *
+     * Use this for cleanup operations or logging that should happen
+     * after every request completes.
+     *
+     * @returns A promise that resolves when the post-run hook completes
+     *
+     * @example
+     * ```typescript
+     * async postRun() {
+     *   await this.logRequestMetrics();
+     * }
+     * ```
+     */
     postRun?(): Promise<void>;
 }
 //# sourceMappingURL=baseAuth.d.ts.map

package/dist/core/auth/baseAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseAuth.d.ts","sourceRoot":"","sources":["../../../src/core/auth/baseAuth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,QAAQ,CAAC,MAAM,GAAG,OAAO;IAC7C;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAExB;;;;;;;;;;;;;;QAcI;IACF,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAC5B"}
+{"version":3,"file":"baseAuth.d.ts","sourceRoot":"","sources":["../../../src/core/auth/baseAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,QAAQ,CAAC,MAAM,GAAG,OAAO;IAC7C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAExB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAC1B"}

package/dist/core/auth/baseAuth.js

@@ -11,12 +11,6 @@
  * type MyAuthCreds = { token: string };
  *
  * export class MyAuth extends AuthBase<MyAuthCreds> {
- *   name = 'my_auth';
- *
- *   async init(scrawn: Scrawn) {
- *     // Setup logic here
- *   }
- *
  *   async getCreds(): Promise<MyAuthCreds> {
  *     return { token: 'my_token' };
  *   }

package/dist/core/auth/baseAuth.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseAuth.js","sourceRoot":"","sources":["../../../src/core/auth/baseAuth.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAgB,QAAQ;CAoE7B"}
+{"version":3,"file":"baseAuth.js","sourceRoot":"","sources":["../../../src/core/auth/baseAuth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAgB,QAAQ;CAmD7B"}

package/dist/core/errors/index.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Comprehensive error handling system for the Scrawn SDK.
+ *
+ * Provides structured error classes with rich metadata for better debugging
+ * and error handling by SDK consumers.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await scrawn.sdkCallEventConsumer({ ... });
+ * } catch (error) {
+ *   if (error instanceof ScrawnAuthenticationError) {
+ *     console.error('Auth failed:', error.message);
+ *     // Refresh API key
+ *   } else if (error instanceof ScrawnNetworkError && error.retryable) {
+ *     // Retry the request
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base error class for all Scrawn SDK errors.
+ * Extends native Error with additional metadata fields.
+ */
+export declare class ScrawnError extends Error {
+    /** Error code for programmatic error handling */
+    readonly code: string;
+    /** Whether this error is retryable */
+    readonly retryable: boolean;
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    /** Request ID for debugging (if available) */
+    readonly requestId?: string;
+    /** Additional error details */
+    readonly details?: Record<string, any>;
+    /** Original error that caused this error (if any) */
+    readonly cause?: Error;
+    constructor(message: string, options: {
+        code: string;
+        retryable?: boolean;
+        statusCode?: number;
+        requestId?: string;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+    /**
+     * Convert error to a plain object for logging/serialization.
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        retryable: boolean;
+        statusCode: number | undefined;
+        requestId: string | undefined;
+        details: Record<string, any> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Authentication or authorization error (401, 403).
+ * Thrown when API key is invalid, expired, or lacks permissions.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnAuthenticationError('Invalid API key', {
+ *   statusCode: 401,
+ *   requestId: 'req_123'
+ * });
+ * ```
+ */
+export declare class ScrawnAuthenticationError extends ScrawnError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * Validation error (400).
+ * Thrown when request payload fails validation.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnValidationError('Invalid userId', {
+ *   details: { field: 'userId', constraint: 'non-empty' }
+ * });
+ * ```
+ */
+export declare class ScrawnValidationError extends ScrawnError {
+    constructor(message: string, options?: {
+        requestId?: string;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * Rate limit error (429).
+ * Thrown when API rate limits are exceeded.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnRateLimitError('Rate limit exceeded', {
+ *   details: { retryAfter: 60 }
+ * });
+ * ```
+ */
+export declare class ScrawnRateLimitError extends ScrawnError {
+    /** Seconds to wait before retrying (if provided by API) */
+    readonly retryAfter?: number;
+    constructor(message: string, options?: {
+        requestId?: string;
+        retryAfter?: number;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * Network-related error (timeout, connection failure, DNS issues).
+ * These are typically retryable.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnNetworkError('Connection timeout', {
+ *   cause: originalError,
+ *   details: { timeout: 30000 }
+ * });
+ * ```
+ */
+export declare class ScrawnNetworkError extends ScrawnError {
+    constructor(message: string, options?: {
+        requestId?: string;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * API error from the Scrawn backend (5xx or other server errors).
+ * May be retryable depending on status code.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnAPIError('Internal server error', {
+ *   statusCode: 500,
+ *   retryable: true,
+ *   requestId: 'req_123'
+ * });
+ * ```
+ */
+export declare class ScrawnAPIError extends ScrawnError {
+    constructor(message: string, options: {
+        statusCode: number;
+        requestId?: string;
+        retryable?: boolean;
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * Configuration error (invalid SDK initialization or settings).
+ * Not retryable - requires code changes.
+ *
+ * @example
+ * ```typescript
+ * throw new ScrawnConfigError('Invalid baseURL format', {
+ *   details: { baseURL: 'invalid-url' }
+ * });
+ * ```
+ */
+export declare class ScrawnConfigError extends ScrawnError {
+    constructor(message: string, options?: {
+        details?: Record<string, any>;
+        cause?: Error;
+    });
+}
+/**
+ * Helper function to convert gRPC errors to Scrawn errors.
+ * Maps gRPC status codes to appropriate Scrawn error types.
+ *
+ * @internal
+ */
+export declare function convertGrpcError(error: unknown, requestId?: string): ScrawnError;
+/**
+ * Helper to check if an error is a Scrawn error.
+ */
+export declare function isScrawnError(error: unknown): error is ScrawnError;
+/**
+ * Helper to check if an error is retryable.
+ */
+export declare function isRetryableError(error: unknown): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/errors/index.d.ts.map

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