@c15t/node-sdk 2.0.0 → 2.0.4

package/README.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <a href="https://c15t.com?utm_source=github&utm_medium=repopage_%40c15t%2Fnode-sdk" target="_blank" rel="noopener noreferrer">
+  <a href="https://c15t.com?utm_source=npm&utm_medium=readme&utm_campaign=oss_readme&utm_content=%40c15t%2Fnode-sdk" target="_blank" rel="noopener noreferrer">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="../../docs/assets/c15t-banner-readme-dark.svg" type="image/svg+xml">
       <img src="../../docs/assets/c15t-banner-readme-light.svg" alt="c15t Banner" type="image/svg+xml">
     </picture>
   </a>
-  <br />
-  <h1 align="center">@c15t/node-sdk: Type-Safe Node.js API Client</h1>
 </p>
 
+# @c15t/node-sdk: Type-Safe Node.js API Client
+
 [![GitHub stars](https://img.shields.io/github/stars/c15t/c15t?style=flat-square)](https://github.com/c15t/c15t)
 [![CI](https://img.shields.io/github/actions/workflow/status/c15t/c15t/ci.yml?style=flat-square)](https://github.com/c15t/c15t/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](https://github.com/c15t/c15t/blob/main/LICENSE.md)
@@ -18,235 +18,61 @@
 [![Last Commit](https://img.shields.io/github/last-commit/c15t/c15t?style=flat-square)](https://github.com/c15t/c15t/commits/main)
 [![Open Issues](https://img.shields.io/github/issues/c15t/c15t?style=flat-square)](https://github.com/c15t/c15t/issues)
 
-A fully typed, lightweight Node.js SDK for seamless interaction with the c15t consent management platform API.
+A fully typed, flexible Node.js SDK for seamless interaction with the c15t consent management platform API.
 
 ## Key Features
 
-- **Type-safe API client** with full TypeScript support
-- **Zero-config setup** with environment variable auto-detection
-- **Result-like error handling** with `unwrap()`, `unwrapOr()`, and `expect()` helpers
-- **Custom error class** (`C15TError`) for typed error handling
-- **Automatic retries** with exponential backoff
-- **Namespaced API methods** for intuitive organization
-- **Lightweight** with minimal dependencies
+- Type-safe API client with full TypeScript support
+- Flexible client configuration with authentication and custom headers
+- Supports dynamic base URL and API prefix configuration
+- Built on top of @orpc/client for robust API interactions
+- Easy integration with Node.js applications
+- Comprehensive error handling and URL validation
 
 ## Prerequisites
 
 - Node.js 18.17.0 or later
-- A Hosted [c15t instance](https://consent.io) (free sign-up) or [self-hosted deployment](https://c15t.com/docs/self-host/v2)
+- A Hosted [c15t instance](https://inth.com) (free sign-up) or [self-hosted deployment](https://c15t.com/docs/self-host/v2)
 
-## Installation
+## Manual Installation
 
 ```bash
-# npm
-npm install @c15t/node-sdk
-
-# pnpm
 pnpm add @c15t/node-sdk
-
-# yarn
-yarn add @c15t/node-sdk
-
-# bun
-bun add @c15t/node-sdk
-```
-
-## Quick Start
-
-### Basic Setup
-
-```typescript
-import { c15tClient } from '@c15t/node-sdk';
-
-// Auto-configure from environment variables
-// Reads C15T_API_URL and C15T_API_TOKEN automatically
-const client = c15tClient();
-
-// Or provide explicit configuration
-const client = c15tClient({
-  baseUrl: 'https://api.example.com',
-  token: 'your-api-token',
-});
 ```
 
-### Environment Variables
-
-The SDK automatically reads these environment variables:
+## Usage
 
-- `C15T_API_URL` - Base URL for the API server
-- `C15T_API_TOKEN` - Authentication token
+1. Import `c15tClient` from `@c15t/node-sdk`
+2. Configure with a base URL and token, or set `C15T_API_URL` and `C15T_API_TOKEN` so the client picks them up automatically
+3. Call API methods on `client.meta`, `client.subjects`, etc. — every method is fully typed
 
-### Check Consent Status
+```ts
+// server.ts
+import { c15tClient } from '@c15t/node-sdk'
 
-```typescript
-const result = await client.checkConsent({
-  externalId: 'user_123',
-  type: 'analytics',
-});
-
-if (result.ok) {
-  console.log('Has consent:', result.data?.results.analytics?.hasConsent);
-} else {
-  console.error('Error:', result.error?.message);
-}
-```
+// Auto-configure from C15T_API_URL + C15T_API_TOKEN env vars
+const client = c15tClient()
 
-### Using Result Helpers
-
-The SDK provides ergonomic helper methods inspired by Rust's Result type:
-
-```typescript
-// Unwrap data or throw if error
-const subject = (await client.getSubject('sub_123')).unwrap();
-
-// Unwrap with custom error message
-const subject = (await client.getSubject('sub_123')).expect('Subject not found');
-
-// Unwrap with default value
-const subject = (await client.getSubject('sub_123')).unwrapOr(defaultSubject);
-
-// Transform data with map
-const name = (await client.getSubject('sub_123')).map(s => s.externalId);
-```
-
-### Error Handling
-
-```typescript
-import { c15tClient, C15TError, isC15TError } from '@c15t/node-sdk';
-
-const client = c15tClient();
+// Or pass options explicitly
+// const client = c15tClient({
+//   baseUrl: process.env.C15T_API_URL!,
+//   token: process.env.C15T_API_TOKEN!,
+// })
 
 try {
-  const subject = (await client.getSubject('sub_123')).unwrap();
+  const status = await client.meta.status()
+  console.log('c15t API status:', status)
+
+  const subject = await client.subjects.create({
+    type: 'cookie_banner',
+    subjectId: 'sub_123',
+    domain: 'example.com',
+    preferences: { analytics: true },
+    givenAt: Date.now(),
+  })
+  console.log('Created subject', subject.id)
 } catch (error) {
-  if (isC15TError(error)) {
-    console.log('Status:', error.status);     // 404
-    console.log('Code:', error.code);         // 'NOT_FOUND'
-    console.log('Details:', error.details);
-    
-    if (error.isNotFound()) {
-      // Handle not found
-    } else if (error.isServerError()) {
-      // Handle server error
-    }
-  }
-}
-```
-
-### Create Subject with Consent
-
-```typescript
-const result = await client.createSubject({
-  type: 'cookie_banner',
-  subjectId: 'sub_123',
-  externalSubjectId: 'user_123',
-  domain: 'example.com',
-  preferences: {
-    analytics: true,
-    marketing: false,
-  },
-  givenAt: Date.now(),
-});
-
-if (result.ok) {
-  console.log('Subject created:', result.data?.subjectId);
-}
-```
-
-### Server Component Usage (Next.js)
-
-```typescript
-// lib/c15t-client.ts
-import { c15tClient } from '@c15t/node-sdk';
-
-export const consentClient = c15tClient({
-  baseUrl: process.env.C15T_API_URL || 'http://localhost:3000/api/self-host',
-});
-
-// app/consent-check/page.tsx
-import { consentClient } from '@/lib/c15t-client';
-
-export default async function ConsentCheckPage({ searchParams }) {
-  const { externalId } = await searchParams;
-  
-  const result = await consentClient.checkConsent({
-    externalId,
-    type: 'analytics',
-  });
-
-  if (!result.ok) {
-    return <div>Error: {result.error?.message}</div>;
-  }
-
-  return <pre>{JSON.stringify(result.data, null, 2)}</pre>;
-}
-```
-
-## API Reference
-
-### Client Methods
-
-| Method | Description |
-|--------|-------------|
-| `client.status()` | Check API status |
-| `client.init()` | Initialize consent manager |
-| `client.checkConsent(query)` | Check consent status |
-| `client.createSubject(input)` | Create a new subject |
-| `client.getSubject(id)` | Get subject by ID |
-| `client.patchSubject(id, input)` | Update subject |
-| `client.listSubjects(query)` | List subjects |
-
-### Namespaced Methods
-
-```typescript
-// Meta operations
-client.meta.status();
-client.meta.init();
-
-// Consent operations
-client.consent.check(query);
-
-// Subject operations
-client.subjects.create(input);
-client.subjects.get(id);
-client.subjects.patch(id, input);
-client.subjects.list(query);
-```
-
-### ResponseContext
-
-All methods return a `ResponseContext<T>` with:
-
-```typescript
-interface ResponseContext<T> {
-  data: T | null;           // Response data
-  error: {...} | null;      // Error details
-  ok: boolean;              // Success status
-  response: Response | null; // Raw Response object
-  
-  // Helper methods
-  unwrap(): T;              // Get data or throw
-  unwrapOr(default: T): T;  // Get data or return default
-  expect(msg: string): T;   // Get data or throw with custom message
-  map<U>(fn: (T) => U): ResponseContext<U>; // Transform data
-}
-```
-
-### Configuration Options
-
-```typescript
-interface C15TClientOptions {
-  baseUrl?: string;           // API base URL (or use C15T_API_URL env var)
-  token?: string;             // Auth token (or use C15T_API_TOKEN env var)
-  headers?: Record<string, string>; // Custom headers
-  prefix?: string;            // API path prefix
-  retryConfig?: {
-    maxRetries?: number;      // Default: 3
-    initialDelayMs?: number;  // Default: 100
-    backoffFactor?: number;   // Default: 2
-    retryableStatusCodes?: number[]; // Default: [500, 502, 503, 504]
-    retryOnNetworkError?: boolean;   // Default: true
-  };
+  console.error('c15t request failed:', error)
 }
 ```
 
@@ -254,24 +80,24 @@ interface C15TClientOptions {
 
 - Join our [Discord community](https://c15t.link/discord)
 - Open an issue on our [GitHub repository](https://github.com/c15t/c15t/issues)
-- Visit [consent.io](https://consent.io) and use the chat widget
-- Contact our support team via email [support@consent.io](mailto:support@consent.io)
+- Visit [inth.com](https://inth.com) and use the chat widget
+- Contact our support team via email [support@inth.com](mailto:support@inth.com)
 
 ## Contributing
 
-- We're open to all community contributions!
+- We're open to all community contributions.
 - Read our [Contribution Guidelines](https://c15t.com/docs/oss/contributing)
 - Review our [Code of Conduct](https://c15t.com/docs/oss/code-of-conduct)
 - Fork the repository
 - Create a new branch for your feature
 - Submit a pull request
-- **All contributions, big or small, are welcome and appreciated!**
+- **All contributions, big or small, are welcome and appreciated.**
 
 ## Security
 
 If you believe you have found a security vulnerability in c15t, we encourage you to **_responsibly disclose this and NOT open a public issue_**. We will investigate all legitimate reports.
 
-Our preference is that you make use of GitHub's private vulnerability reporting feature to disclose potential security vulnerabilities in our Open Source Software. To do this, please visit [https://github.com/c15t/c15t/security](https://github.com/c15t/c15t/security) and click the "Report a vulnerability" button.
+Our preference is that you make use of GitHub's private vulnerability reporting feature to disclose potential security vulnerabilities in our open-source software. To do this, please visit [https://github.com/c15t/c15t/security](https://github.com/c15t/c15t/security) and click the "Report a vulnerability" button.
 
 ### Security Policy
 
@@ -286,4 +112,4 @@ Our preference is that you make use of GitHub's private vulnerability reporting
 
 ---
 
-**Built by [Inth](https://inth.com?utm_source=github&utm_medium=repopage_%40c15t%2Fnode-sdk)**
+**Built by [Inth](https://inth.com?utm_source=npm&utm_medium=readme&utm_campaign=oss_readme&utm_content=%40c15t%2Fnode-sdk)**

package/dist/testing.cjs

@@ -0,0 +1,119 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createMockClient: ()=>createMockClient,
+    createMockErrorResponse: ()=>createMockErrorResponse,
+    createMockResponse: ()=>createMockResponse
+});
+function createMockResponse(data, options = {}) {
+    const isSuccess = options.ok ?? true;
+    const error = options.error ?? null;
+    const response = options.response ?? null;
+    return {
+        data: isSuccess ? data : null,
+        error,
+        ok: isSuccess,
+        response,
+        unwrap () {
+            if (!isSuccess || null === data) throw new Error(error?.message || 'Request failed');
+            return data;
+        },
+        unwrapOr (defaultValue) {
+            if (!isSuccess || null === data) return defaultValue;
+            return data;
+        },
+        expect (message) {
+            if (!isSuccess || null === data) throw new Error(message);
+            return data;
+        },
+        map (fn) {
+            if (!isSuccess || null === data) return createMockResponse(null, {
+                ok: false,
+                error: error ?? void 0
+            });
+            return createMockResponse(fn(data));
+        }
+    };
+}
+function createMockErrorResponse(error) {
+    return createMockResponse(null, {
+        ok: false,
+        error
+    });
+}
+function createMockClient(overrides = {}) {
+    const defaultNotImplemented = ()=>createMockErrorResponse({
+            message: 'Method not implemented in mock',
+            status: 501,
+            code: 'NOT_IMPLEMENTED'
+        });
+    const status = overrides.status ?? defaultNotImplemented;
+    const init = overrides.init ?? defaultNotImplemented;
+    const checkConsent = overrides.checkConsent ?? defaultNotImplemented;
+    const createSubject = overrides.createSubject ?? defaultNotImplemented;
+    const getSubject = overrides.getSubject ?? defaultNotImplemented;
+    const patchSubject = overrides.patchSubject ?? defaultNotImplemented;
+    const listSubjects = overrides.listSubjects ?? defaultNotImplemented;
+    return {
+        status: ()=>Promise.resolve(status()),
+        init: ()=>Promise.resolve(init()),
+        checkConsent: (query)=>Promise.resolve(checkConsent(query)),
+        createSubject: (input)=>Promise.resolve(createSubject(input)),
+        getSubject: (id)=>Promise.resolve(getSubject(id)),
+        patchSubject: (id, input)=>Promise.resolve(patchSubject({
+                id,
+                ...'object' == typeof input && null !== input ? input : {}
+            })),
+        listSubjects: (query)=>Promise.resolve(listSubjects(query)),
+        consent: {
+            check: (query)=>Promise.resolve(checkConsent(query))
+        },
+        subjects: {
+            create: (input)=>Promise.resolve(createSubject(input)),
+            get: (id)=>Promise.resolve(getSubject(id)),
+            patch: (id, input)=>Promise.resolve(patchSubject({
+                    id,
+                    ...'object' == typeof input && null !== input ? input : {}
+                })),
+            list: (query)=>Promise.resolve(listSubjects(query))
+        },
+        meta: {
+            status: ()=>Promise.resolve(status()),
+            init: ()=>Promise.resolve(init())
+        }
+    };
+}
+exports.createMockClient = __webpack_exports__.createMockClient;
+exports.createMockErrorResponse = __webpack_exports__.createMockErrorResponse;
+exports.createMockResponse = __webpack_exports__.createMockResponse;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createMockClient",
+    "createMockErrorResponse",
+    "createMockResponse"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/testing.js

@@ -0,0 +1,79 @@
+function createMockResponse(data, options = {}) {
+    const isSuccess = options.ok ?? true;
+    const error = options.error ?? null;
+    const response = options.response ?? null;
+    return {
+        data: isSuccess ? data : null,
+        error,
+        ok: isSuccess,
+        response,
+        unwrap () {
+            if (!isSuccess || null === data) throw new Error(error?.message || 'Request failed');
+            return data;
+        },
+        unwrapOr (defaultValue) {
+            if (!isSuccess || null === data) return defaultValue;
+            return data;
+        },
+        expect (message) {
+            if (!isSuccess || null === data) throw new Error(message);
+            return data;
+        },
+        map (fn) {
+            if (!isSuccess || null === data) return createMockResponse(null, {
+                ok: false,
+                error: error ?? void 0
+            });
+            return createMockResponse(fn(data));
+        }
+    };
+}
+function createMockErrorResponse(error) {
+    return createMockResponse(null, {
+        ok: false,
+        error
+    });
+}
+function createMockClient(overrides = {}) {
+    const defaultNotImplemented = ()=>createMockErrorResponse({
+            message: 'Method not implemented in mock',
+            status: 501,
+            code: 'NOT_IMPLEMENTED'
+        });
+    const status = overrides.status ?? defaultNotImplemented;
+    const init = overrides.init ?? defaultNotImplemented;
+    const checkConsent = overrides.checkConsent ?? defaultNotImplemented;
+    const createSubject = overrides.createSubject ?? defaultNotImplemented;
+    const getSubject = overrides.getSubject ?? defaultNotImplemented;
+    const patchSubject = overrides.patchSubject ?? defaultNotImplemented;
+    const listSubjects = overrides.listSubjects ?? defaultNotImplemented;
+    return {
+        status: ()=>Promise.resolve(status()),
+        init: ()=>Promise.resolve(init()),
+        checkConsent: (query)=>Promise.resolve(checkConsent(query)),
+        createSubject: (input)=>Promise.resolve(createSubject(input)),
+        getSubject: (id)=>Promise.resolve(getSubject(id)),
+        patchSubject: (id, input)=>Promise.resolve(patchSubject({
+                id,
+                ...'object' == typeof input && null !== input ? input : {}
+            })),
+        listSubjects: (query)=>Promise.resolve(listSubjects(query)),
+        consent: {
+            check: (query)=>Promise.resolve(checkConsent(query))
+        },
+        subjects: {
+            create: (input)=>Promise.resolve(createSubject(input)),
+            get: (id)=>Promise.resolve(getSubject(id)),
+            patch: (id, input)=>Promise.resolve(patchSubject({
+                    id,
+                    ...'object' == typeof input && null !== input ? input : {}
+                })),
+            list: (query)=>Promise.resolve(listSubjects(query))
+        },
+        meta: {
+            status: ()=>Promise.resolve(status()),
+            init: ()=>Promise.resolve(init())
+        }
+    };
+}
+export { createMockClient, createMockErrorResponse, createMockResponse };

package/package.json

@@ -1,25 +1,27 @@
 {
 	"name": "@c15t/node-sdk",
-	"version": "2.0.0",
+	"version": "2.0.4",
 	"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",
+		"c15t",
+		"node",
+		"nodejs",
+		"sdk",
 		"consent",
+		"consent-api",
+		"consent-management",
 		"privacy",
 		"gdpr",
 		"ccpa",
 		"lgpd",
-		"headless",
-		"typescript",
-		"cookie-banner",
-		"consent-management-platform",
 		"cmp",
-		"consent-banner",
-		"user-consent",
-		"privacy-compliance",
-		"web-privacy"
+		"typescript",
+		"server-side"
 	],
 	"homepage": "https://c15t.com",
+	"bugs": {
+		"url": "https://github.com/c15t/c15t/issues"
+	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/c15t/c15t.git",
@@ -50,14 +52,14 @@
 		"build": "rslib build && bun ../../scripts/normalize-dist-types.mjs",
 		"check-types": "tsc --noEmit",
 		"check-types:test": "tsc -p tsconfig.test.json",
-		"dev": "rslib build --watch",
+		"dev": "sh -c 'rslib build --no-dts --no-clean && rslib build --watch --no-dts --no-clean'",
 		"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/backend": "2.0.0",
+		"@c15t/backend": "2.0.4",
 		"@orpc/client": "1.13.13",
 		"@orpc/contract": "1.13.13",
 		"@orpc/openapi-client": "^1.13.13",

package/readme.json

@@ -11,13 +11,15 @@
 	],
 	"prerequisites": [
 		"Node.js 18.17.0 or later",
-		"A Hosted [c15t instance](https://consent.io) (free sign-up) or [self-hosted deployment](https://c15t.com/docs/self-host/v2)"
+		"A Hosted [c15t instance](https://inth.com) (free sign-up) or [self-hosted deployment](https://c15t.com/docs/self-host/v2)"
 	],
 	"manualInstallation": ["", "```bash\npnpm add @c15t/node-sdk\n```"],
 	"usage": [
-		"Import the c15tClient function from the SDK",
-		"Configure the client with your API base URL",
-		"Interact with the c15t API using type-safe methods"
+		"Import `c15tClient` from `@c15t/node-sdk`",
+		"Configure with a base URL and token, or set `C15T_API_URL` and `C15T_API_TOKEN` so the client picks them up automatically",
+		"Call API methods on `client.meta`, `client.subjects`, etc. — every method is fully typed",
+
+		"```ts\n// server.ts\nimport { c15tClient } from '@c15t/node-sdk'\n\n// Auto-configure from C15T_API_URL + C15T_API_TOKEN env vars\nconst client = c15tClient()\n\n// Or pass options explicitly\n// const client = c15tClient({\n//   baseUrl: process.env.C15T_API_URL!,\n//   token: process.env.C15T_API_TOKEN!,\n// })\n\ntry {\n  const status = await client.meta.status()\n  console.log('c15t API status:', status)\n\n  const subject = await client.subjects.create({\n    type: 'cookie_banner',\n    subjectId: 'sub_123',\n    domain: 'example.com',\n    preferences: { analytics: true },\n    givenAt: Date.now(),\n  })\n  console.log('Created subject', subject.id)\n} catch (error) {\n  console.error('c15t request failed:', error)\n}\n```"
 	],
 	"showCLIGeneration": false
 }