@c15t/backend 0.0.1-rc.10

package/dist/client/index.d.ts

@@ -0,0 +1,203 @@
+import type { ConsentPurpose } from '../db/schema/consent-purpose';
+import type { FetchOptions, ResponseContext, c15tClientOptions } from './types';
+/**
+ * Client for interacting with the c15t consent management API.
+ *
+ * This class provides methods for retrieving and updating consent preferences,
+ * listing consent purposes, and accessing consent history. It handles HTTP requests
+ * to the c15t API and provides a type-safe interface for working with consent data.
+ *
+ * @remarks
+ * The client abstracts away the details of making HTTP requests to the c15t API,
+ * handling authentication, error handling, and response parsing. It provides
+ * a clean, type-safe interface for working with consent data.
+ *
+ * @example
+ * ```typescript
+ * import { createConsentClient } from '@c15t/client';
+ *
+ * const client = createConsentClient({
+ *   baseURL: 'https://example.com/api',
+ *   headers: { 'X-API-Key': 'your-api-key' }
+ * });
+ *
+ * // Get current consent
+ * const { data, error } = await client.getConsent();
+ *
+ * // Update consent
+ * await client.updateConsent({
+ *   analytics: true,
+ *   marketing: false
+ * });
+ * ```
+ */
+export declare class c15tClient {
+    /**
+     * Base URL for API requests (without trailing slash)
+     *
+     * @internal
+     */
+    private baseURL;
+    /**
+     * Default headers to include with all requests
+     *
+     * @internal
+     */
+    private headers;
+    /**
+     * Custom fetch implementation (if provided)
+     *
+     * @internal
+     */
+    private customFetch?;
+    /**
+     * Creates a new c15t client instance.
+     *
+     * @param options - Configuration options for the client
+     * @throws Will throw an error if the baseURL is invalid or if required options are missing
+     */
+    constructor(options: c15tClientOptions);
+    /**
+     * Generic method for making HTTP requests to the API.
+     *
+     * This internal method handles constructing the request, processing the response,
+     * and executing any callbacks based on the response status. It provides standardized
+     * error handling and response formatting.
+     *
+     * @typeParam ResponseType - The expected type of the response data
+     * @param path - API endpoint path (will be appended to the baseURL)
+     * @param options - Request configuration options
+     * @returns A response context object containing the data, response metadata, and any errors
+     * @throws Will throw an error if options.throw is true and the request fails
+     * @internal This method is not intended to be used directly, use the public API methods instead
+     */
+    private fetcher;
+    /**
+     * Lists all available consent purposes.
+     *
+     * This method retrieves all consent purposes configured in the system,
+     * including their IDs, names, descriptions, and whether they are required
+     * or optional.
+     *
+     * @throws Will throw an error if options.throw is true and the request fails
+     *
+     * @example
+     * ```typescript
+     * const { data, error } = await client.listPurposes();
+     *
+     * if (error) {
+     *   console.error('Failed to fetch purposes:', error.message);
+     *   return;
+     * }
+     *
+     * if (data) {
+     *   // Display available consent purposes to the subject
+     *   data.forEach(consentPurpose => {
+     *     console.log(`${consentPurpose.name}: ${consentPurpose.description}`);
+     *     console.log(`Required: ${consentPurpose.required}`);
+     *   });
+     * }
+     * ```
+     *
+     * @param options - Optional fetch configuration options
+     * @returns Response context containing the list of consent purposes if successful
+     */
+    listPurposes(options?: FetchOptions<ConsentPurpose[]>): Promise<ResponseContext<ConsentPurpose[]>>;
+    /**
+     * Makes a custom API request to any endpoint.
+     *
+     * This method allows for making requests to custom endpoints not covered
+     * by the standard methods, such as plugin-specific endpoints.
+     *
+     * @typeParam ResponseType - The expected type of the response data
+     * @param path - The API endpoint path
+     * @param options - Request configuration options
+     * @returns Response context containing the requested data if successful
+     * @throws Will throw an error if options.throw is true and the request fails
+     *
+     * @example
+     * ```typescript
+     * // Call a custom analytics endpoint with error handling
+     * try {
+     *   const { data, error } = await client.$fetch<AnalyticsResponse>('/analytics/track', {
+     *     method: 'POST',
+     *     body: {
+     *       event: 'page_view',
+     *       properties: { page: '/home' }
+     *     },
+     *     throw: true // Automatically throw on error
+     *   });
+     *
+     *   console.log('Event tracked successfully:', data);
+     * } catch (error) {
+     *   console.error('Failed to track event:', error);
+     * }
+     *
+     * // Using callbacks for success/error handling
+     * await client.$fetch('/analytics/track', {
+     *   method: 'POST',
+     *   body: { event: 'button_click' },
+     *   onSuccess: ({ data }) => console.log('Tracked:', data),
+     *   onError: ({ error }) => console.error('Failed:', error.message)
+     * });
+     * ```
+     */
+    $fetch<ResponseType>(path: string, options?: FetchOptions<ResponseType>): Promise<ResponseContext<ResponseType>>;
+}
+/**
+ * Creates and returns a new c15t client instance.
+ *
+ * This is the recommended way to create a client for interacting with the c15t API.
+ * It provides a convenient factory function that instantiates a properly configured
+ * client based on the provided options.
+ *
+ * @throws Will throw an error if the baseURL is invalid or if required options are missing
+ *
+ * @example
+ * ```typescript
+ * import { createConsentClient } from '@c15t/client';
+ *
+ * // Create a client for your application
+ * const client = createConsentClient({
+ *   baseURL: 'https://api.example.com/consent',
+ *   headers: {
+ *     'X-API-Key': process.env.API_KEY,
+ *     'user-agent': 'MyConsentApp/1.0'
+ *   },
+ *   fetchOptions: {
+ *     // Optional custom fetch implementation
+ *     customFetchImpl: customFetch
+ *   }
+ * });
+ *
+ * // Use the client in your application
+ * async function handleConsentFlow() {
+ *   // Get available purposes
+ *   const { data: purposes, error } = await client.listPurposes();
+ *
+ *   if (error) {
+ *     console.error('Failed to load consent purposes:', error.message);
+ *     return;
+ *   }
+ *
+ *   // Display purposes to subject and collect their choices
+ *   // ...
+ *
+ *   // Then update their consent
+ *   const userChoices = {
+ *     analytics: true,
+ *     marketing: false
+ *   };
+ *
+ *   await client.$fetch('/update-consent', {
+ *     method: 'POST',
+ *     body: { preferences: userChoices }
+ *   });
+ * }
+ * ```
+ *
+ * @param options - Configuration options for the client
+ * @returns A new c15tClient instance
+ */
+export declare function createConsentClient(options: c15tClientOptions): c15tClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;IACtB;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAS;IAExB;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAyB;IAExC;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAC,CAAe;IAEnC;;;;;OAKG;gBACS,OAAO,EAAE,iBAAiB;IAatC;;;;;;;;;;;;;OAaG;YACW,OAAO;IAgKrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,YAAY,CACjB,OAAO,CAAC,EAAE,YAAY,CAAC,cAAc,EAAE,CAAC,GACtC,OAAO,CAAC,eAAe,CAAC,cAAc,EAAE,CAAC,CAAC;IAqF7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,MAAM,CAAC,YAAY,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,GAClC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;CAGzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAE1E"}

package/dist/client/index.js

@@ -0,0 +1,106 @@
+class c15tClient {
+    baseURL;
+    headers;
+    customFetch;
+    constructor(options){
+        this.baseURL = options.baseURL.endsWith('/') ? options.baseURL.slice(0, -1) : options.baseURL;
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...options.headers
+        };
+        this.customFetch = options.fetchOptions?.customFetchImpl;
+    }
+    async fetcher(path, options = {}) {
+        try {
+            const url = new URL(path, this.baseURL);
+            if (options.query) {
+                for (const [key, value] of Object.entries(options.query))if (void 0 !== value) {
+                    if (Array.isArray(value)) for (const v of value)url.searchParams.append(key, String(v));
+                    else url.searchParams.append(key, String(value));
+                }
+            }
+            const fetchOptions = {
+                method: options.method || 'GET',
+                headers: {
+                    ...this.headers,
+                    ...options.headers
+                }
+            };
+            if (options.body && 'GET' !== fetchOptions.method) fetchOptions.body = JSON.stringify(options.body);
+            const fetchImpl = this.customFetch || fetch;
+            const response = await fetchImpl(url.toString(), fetchOptions);
+            let data = null;
+            let error = null;
+            if (204 !== response.status) try {
+                data = await response.json();
+            } catch (err) {
+                if (response.ok) data = null;
+                else error = new Error(`Failed to parse response: ${err.message}`);
+            }
+            const context = {
+                data,
+                response,
+                error: error ? {
+                    message: error.message,
+                    status: response.status
+                } : null,
+                ok: response.ok
+            };
+            if (response.ok) {
+                if (options.onSuccess) await options.onSuccess(context);
+            } else {
+                if (options.onError) await options.onError(context);
+                if (options.throw) {
+                    const error = new Error(`Request failed with status ${response.status}`);
+                    Object.assign(error, {
+                        status: response.status,
+                        data
+                    });
+                    throw error;
+                }
+            }
+            return context;
+        } catch (error) {
+            if (options.onError) {
+                const errorObj = error;
+                const context = {
+                    data: null,
+                    error: {
+                        message: errorObj.message || 'Request failed',
+                        status: error.status || 500,
+                        code: error.code
+                    },
+                    ok: false,
+                    response: null
+                };
+                await options.onError(context);
+                if (options.throw) throw error;
+                return context;
+            }
+            if (options.throw) throw error;
+            return {
+                data: null,
+                error: {
+                    message: error.message || 'Request failed',
+                    status: error.status || 500,
+                    code: error.code
+                },
+                ok: false,
+                response: null
+            };
+        }
+    }
+    async listPurposes(options) {
+        return this.fetcher('/list-purposes', {
+            method: 'GET',
+            ...options
+        });
+    }
+    async $fetch(path, options) {
+        return this.fetcher(path, options);
+    }
+}
+function createConsentClient(options) {
+    return new c15tClient(options);
+}
+export { c15tClient, createConsentClient };