@c15t/node-sdk 1.8.0 → 2.0.0-rc.0

package/dist/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Configuration options for the C15T SDK client
+ */
+export interface C15TClientOptions {
+    /**
+     * Base URL for the API server.
+     * If not provided, falls back to C15T_API_URL environment variable.
+     * @example "https://api.example.com"
+     */
+    baseUrl?: string;
+    /**
+     * Authentication token (if needed).
+     * If not provided, falls back to C15T_API_TOKEN environment variable.
+     * @example "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+     */
+    token?: string;
+    /**
+     * Additional headers to include with each request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Prefix path for API endpoints
+     * @default "/"
+     */
+    prefix?: string;
+    /**
+     * Retry configuration for failed requests
+     */
+    retryConfig?: RetryConfig;
+    /**
+     * Enable debug mode to log requests and responses.
+     * Can also be enabled via C15T_DEBUG=true environment variable.
+     * @default false
+     * @example
+     * ```typescript
+     * const client = c15tClient({
+     *   baseUrl: 'https://api.example.com',
+     *   debug: true,
+     * });
+     * // Console output:
+     * // [c15t] GET /status (142ms) -> 200
+     * ```
+     */
+    debug?: boolean;
+    /**
+     * Request timeout in milliseconds.
+     * Requests exceeding this timeout will be aborted.
+     * @default 30000 (30 seconds)
+     * @example
+     * ```typescript
+     * const client = c15tClient({
+     *   baseUrl: 'https://api.example.com',
+     *   timeout: 5000, // 5 seconds
+     * });
+     * ```
+     */
+    timeout?: number;
+}
+/**
+ * Retry configuration for HTTP requests
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before the first retry
+     * @default 100
+     */
+    initialDelayMs?: number;
+    /**
+     * Factor by which the delay increases for each subsequent retry
+     * @default 2
+     */
+    backoffFactor?: number;
+    /**
+     * Array of HTTP status codes that should trigger a retry
+     * @default [500, 502, 503, 504]
+     */
+    retryableStatusCodes?: number[];
+    /**
+     * Array of HTTP status codes that should never be retried
+     * @default [400, 401, 403, 404]
+     */
+    nonRetryableStatusCodes?: number[];
+    /**
+     * Whether to retry on network errors
+     * @default true
+     */
+    retryOnNetworkError?: boolean;
+}
+/**
+ * Response context returned from API requests.
+ *
+ * Provides Result-like helper methods for ergonomic error handling.
+ */
+export interface ResponseContext<T = unknown> {
+    /**
+     * Response data returned by the API
+     */
+    data: T | null;
+    /**
+     * Original fetch Response object
+     */
+    response: Response | null;
+    /**
+     * Error information if the request failed
+     */
+    error: {
+        /**
+         * Error message describing what went wrong
+         */
+        message: string;
+        /**
+         * HTTP status code or custom error code
+         */
+        status: number;
+        /**
+         * Optional error code for more specific error identification
+         */
+        code?: string;
+        /**
+         * Optional cause of the error
+         */
+        cause?: unknown;
+        /**
+         * Optional additional details about the error
+         */
+        details?: Record<string, unknown> | null;
+    } | null;
+    /**
+     * Whether the request was successful
+     */
+    ok: boolean;
+    /**
+     * Unwraps the response data, throwing an error if the request failed.
+     *
+     * @throws {Error} If the request was not successful
+     * @returns The response data
+     *
+     * @example
+     * ```typescript
+     * const subject = (await client.getSubject('sub_123')).unwrap();
+     * ```
+     */
+    unwrap(): T;
+    /**
+     * Unwraps the response data, returning a default value if the request failed.
+     *
+     * @param defaultValue - The value to return if the request failed
+     * @returns The response data or the default value
+     *
+     * @example
+     * ```typescript
+     * const subject = (await client.getSubject('sub_123')).unwrapOr(defaultSubject);
+     * ```
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Unwraps the response data, throwing a custom error message if the request failed.
+     *
+     * @param message - Custom error message to throw
+     * @throws {Error} With the provided message if the request was not successful
+     * @returns The response data
+     *
+     * @example
+     * ```typescript
+     * const subject = (await client.getSubject('sub_123')).expect('Subject not found');
+     * ```
+     */
+    expect(message: string): T;
+    /**
+     * Maps the response data to a new value if successful.
+     *
+     * @param fn - Function to transform the data
+     * @returns A new ResponseContext with the transformed data
+     *
+     * @example
+     * ```typescript
+     * const name = (await client.getSubject('sub_123')).map(s => s.name);
+     * ```
+     */
+    map<U>(fn: (data: T) => U): ResponseContext<U>;
+}
+/**
+ * Options for individual fetch requests
+ */
+export interface FetchOptions<ResponseType = unknown, BodyType = unknown, QueryType = unknown> {
+    /**
+     * HTTP method for the request
+     * @default 'GET'
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /**
+     * Request body to send with the request
+     */
+    body?: BodyType;
+    /**
+     * Query parameters to include in the request URL
+     */
+    query?: QueryType;
+    /**
+     * Custom headers to include with this specific request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to throw an error when the response is not successful
+     * @default false
+     */
+    throw?: boolean;
+    /**
+     * Callback function to execute on successful response
+     */
+    onSuccess?: (context: ResponseContext<ResponseType>) => void | Promise<void>;
+    /**
+     * Callback function to execute on error response
+     */
+    onError?: (context: ResponseContext<ResponseType>, path: string) => void | Promise<void>;
+    /**
+     * Request-specific retry configuration
+     */
+    retryConfig?: RetryConfig;
+    /**
+     * Request timeout in milliseconds.
+     * Overrides the global timeout for this specific request.
+     * @example
+     * ```typescript
+     * await client.getSubject('sub_123', undefined, { timeout: 5000 });
+     * ```
+     */
+    timeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,73 +1,68 @@
 {
-  "name": "@c15t/node-sdk",
-  "version": "1.8.0",
-  "description": "Official Node.js SDK for c15t. Connects to the Consent Engine to read and write consent records and preferences. TypeScript-first, simple APIs, built-in auth and retries.",
-  "keywords": [
-    "react",
-    "consent",
-    "privacy",
-    "gdpr",
-    "ccpa",
-    "lgpd",
-    "headless",
-    "typescript",
-    "cookie-banner",
-    "consent-management-platform",
-    "cmp",
-    "consent-banner",
-    "user-consent",
-    "privacy-compliance",
-    "web-privacy"
-  ],
-  "homepage": "https://c15t.com",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/c15t/c15t.git",
-    "directory": "packages/node-sdk"
-  },
-  "license": "GPL-3.0-only",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@orpc/client": "1.8.1",
-    "@orpc/contract": "1.8.1",
-    "@orpc/openapi-client": "^1.8.1",
-    "@orpc/server": "1.8.1",
-    "@c15t/backend": "1.8.0"
-  },
-  "devDependencies": {
-    "@electric-sql/pglite": "0.2.17",
-    "@libsql/kysely-libsql": "^0.4.1",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/express": "^5.0.1",
-    "@types/node": "20.14.13",
-    "@types/pg": "8.11.6",
-    "kysely-pglite": "^0.6.1",
-    "msw": "^2.7.6",
-    "typescript": "^5.8.3",
-    "@c15t/typescript-config": "0.0.1-beta.1",
-    "@c15t/vitest-config": "1.0.0"
-  },
-  "scripts": {
-    "build": "rslib build",
-    "check-types": "tsc --noEmit",
-    "check-types:test": "tsc -p tsconfig.test.json",
-    "dev": "rslib build --watch",
-    "fmt": "pnpm biome format --write . && pnpm biome check --formatter-enabled=false --linter-enabled=false --write",
-    "lint": "pnpm biome lint ./src",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  }
-}
+	"name": "@c15t/node-sdk",
+	"version": "2.0.0-rc.0",
+	"description": "Official Node.js SDK for c15t. Connects to the Consent Engine to read and write consent records and preferences. TypeScript-first, simple APIs, built-in auth and retries.",
+	"keywords": [
+		"react",
+		"consent",
+		"privacy",
+		"gdpr",
+		"ccpa",
+		"lgpd",
+		"headless",
+		"typescript",
+		"cookie-banner",
+		"consent-management-platform",
+		"cmp",
+		"consent-banner",
+		"user-consent",
+		"privacy-compliance",
+		"web-privacy"
+	],
+	"homepage": "https://c15t.com",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/c15t/c15t.git",
+		"directory": "packages/node-sdk"
+	},
+	"license": "GPL-3.0-only",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./testing": {
+			"types": "./dist/testing.d.ts",
+			"import": "./dist/testing.js",
+			"require": "./dist/testing.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rslib build",
+		"check-types": "tsc --noEmit",
+		"check-types:test": "tsc -p tsconfig.test.json",
+		"dev": "rslib build",
+		"fmt": "bun biome format --write . && bun biome check --formatter-enabled=false --linter-enabled=false --write",
+		"lint": "bun biome lint ./src",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"dependencies": {
+		"@c15t/schema": "workspace:*"
+	},
+	"devDependencies": {
+		"@c15t/backend": "workspace:*",
+		"@c15t/typescript-config": "workspace:*",
+		"@c15t/vitest-config": "workspace:*",
+		"@types/node": "24.10.1",
+		"typescript": "5.9.3"
+	}
+}