sct-client 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# @sct/client
+
+Official Node.js/TypeScript SDK for the **SCT (Secure Compact Tokenization)** API — pseudonymize PII, restore pseudonymized data, detect PII in free text, and optimize LLM token usage, all through one typed client.
+
+## Requirements
+
+- Node.js `>=18` (uses the global `fetch` API)
+- An SCT API key ([get one here](https://sct.simosphereai.com))
+
+## Installation
+
+```bash
+npm install @sct/client
+```
+
+## Quick Start
+
+```ts
+import { SCTClient } from '@sct/client';
+
+const client = new SCTClient({
+  apiKey: process.env.SCT_API_KEY!,
+  // baseUrl defaults to 'https://sct.simosphereai.com/api/v1'
+});
+
+const result = await client.pseudonymize(
+  JSON.stringify({
+    name: 'Max Mustermann',
+    email: 'max@example.com',
+    iban: 'DE89370400440532013000',
+  }),
+  { format: 'json', autoDetectPii: true },
+);
+
+console.log(result.pseudonymized_data);
+console.log(result.encryption_key);
+```
+
+## Configuration
+
+```ts
+const client = new SCTClient({
+  apiKey: 'sct_your_api_key',
+  baseUrl: 'https://sct.simosphereai.com/api/v1', // optional
+  timeoutMs: 10_000, // optional, aborts the request after this duration
+});
+```
+
+## API
+
+### `pseudonymize(data, options?)`
+
+Replace PII in structured or free-text data with reversible pseudonyms.
+
+```ts
+const result = await client.pseudonymize(csvData, {
+  format: 'csv',
+  method: 'aes-256-gcm', // 'aes-256-gcm' | 'fpe-ff1'
+  fields: ['name', 'email'], // only pseudonymize these fields
+  // excludeFields: ['amount', 'currency'], // ...or exclude these instead
+  autoDetectPii: true, // NLP-based PII detection
+});
+
+// result.pseudonymized_data
+// result.encryption_key
+// result.fields_encrypted
+// result.detected_entities
+// result.record_count
+```
+
+### `dePseudonymize(data, encryptionKey, options?)`
+
+Restore data that was previously pseudonymized, using the key returned by `pseudonymize`.
+
+```ts
+const restored = await client.dePseudonymize(result.pseudonymized_data, result.encryption_key, {
+  format: 'json',
+});
+
+console.log(restored.original_data);
+```
+
+### `detectPii(text)`
+
+Scan free text for PII entities (names, emails, phone numbers, IBANs, addresses, IDs, IP addresses) without pseudonymizing it.
+
+```ts
+const detection = await client.detectPii('Contact Max Mustermann at max@example.com.');
+
+for (const entity of detection.entities) {
+  console.log(`${entity.entity_type}: ${entity.value} (confidence ${entity.confidence})`);
+}
+```
+
+### `optimizeTokens(text, targetModel?, targetReduction?)`
+
+Reduce LLM token consumption for a piece of text while preserving its meaning.
+
+```ts
+const optimized = await client.optimizeTokens(
+  'Your verbose text content that could be optimized...',
+  'gpt-4o', // 'gpt-4' | 'gpt-4o' | 'claude-3' | 'custom'
+  0.3, // target reduction ratio, 0.0–0.9
+);
+
+console.log(optimized.optimized_text);
+console.log(`${optimized.reduction_percent}% smaller (${optimized.tokens_saved} tokens saved)`);
+```
+
+### `countTokens(text, model?)`
+
+Count tokens for a text/model pair without modifying the content.
+
+```ts
+const { token_count } = await client.countTokens('Your text content here...', 'gpt-4o');
+```
+
+## Error Handling
+
+All methods reject with an `SCTError` on non-2xx responses, network failures, or timeouts.
+
+```ts
+import { SCTClient, SCTError } from '@sct/client';
+
+try {
+  await client.pseudonymize(invalidPayload);
+} catch (error) {
+  if (error instanceof SCTError) {
+    console.error(`SCT API error (${error.statusCode}): ${error.message}`);
+    // error.statusCode is 0 for network/timeout failures
+  } else {
+    throw error;
+  }
+}
+```
+
+## Full Example: PII-Safe LLM Round-Trip
+
+```ts
+import { SCTClient } from '@sct/client';
+
+const client = new SCTClient({ apiKey: process.env.SCT_API_KEY! });
+
+const prompt = 'Please draft a follow-up email to Max Mustermann (max@example.com).';
+
+// 1. Pseudonymize before sending to an LLM provider
+const { pseudonymized_data, encryption_key } = await client.pseudonymize(prompt, {
+  format: 'text',
+  autoDetectPii: true,
+});
+
+// 2. ... send pseudonymized_data to your LLM provider, get llmResponse back ...
+
+// 3. Restore the original PII in the LLM's response
+const { original_data } = await client.dePseudonymize(llmResponse, encryption_key, {
+  format: 'text',
+});
+
+console.log(original_data);
+```
+
+## TypeScript
+
+This package ships its own type declarations — no `@types` package needed. All response and option types are exported from the package root:
+
+```ts
+import type {
+  SCTClientOptions,
+  PseudonymizeOptions,
+  PseudonymizeResult,
+  DePseudonymizeOptions,
+  DePseudonymizeResult,
+  DetectPIIResult,
+  DetectedEntity,
+  OptimizeResult,
+  TokenCountResult,
+  DataFormat,
+  EncryptionMethod,
+  TokenizerModel,
+} from '@sct/client';
+```
+
+## License
+
+UNLICENSED — SIMO GmbH internal / commercial use only.

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+import type { DataFormat, DePseudonymizeOptions, DePseudonymizeResult, DetectPIIResult, EncryptionMethod, OptimizeResult, PseudonymizeOptions, PseudonymizeResult, SCTClientOptions, TokenCountResult, TokenizerModel } from './types.js';
+/** Error thrown for any non-2xx response or network/transport failure. */
+export declare class SCTError extends Error {
+    /** HTTP status code, or 0 when the request never reached the server. */
+    readonly statusCode: number;
+    /** Raw error payload returned by the API, when available. */
+    readonly details?: unknown;
+    constructor(message: string, statusCode: number, details?: unknown);
+}
+/**
+ * Client for the SCT (Secure Compact Tokenization) API.
+ *
+ * @example
+ * ```ts
+ * const client = new SCTClient({ apiKey: process.env.SCT_API_KEY! });
+ * const result = await client.pseudonymize(
+ *   JSON.stringify({ name: 'Max Mustermann', email: 'max@example.com' }),
+ *   { format: 'json', autoDetectPii: true },
+ * );
+ * console.log(result.pseudonymized_data);
+ * ```
+ */
+export declare class SCTClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs?;
+    constructor(options: SCTClientOptions);
+    /**
+     * Pseudonymize PII within structured or free-text data.
+     *
+     * @param data - The raw data to pseudonymize (JSON string, CSV, XML, or plain text).
+     * @param options - Format, encryption, and field-selection options.
+     */
+    pseudonymize(data: string, options?: PseudonymizeOptions): Promise<PseudonymizeResult>;
+    /**
+     * Restore data that was previously pseudonymized.
+     *
+     * @param data - The pseudonymized data to restore.
+     * @param encryptionKey - The encryption key returned by {@link pseudonymize}.
+     * @param options - Format, encryption, and field-selection options.
+     */
+    dePseudonymize(data: string, encryptionKey: string, options?: DePseudonymizeOptions): Promise<DePseudonymizeResult>;
+    /**
+     * Detect PII entities within free text without pseudonymizing it.
+     *
+     * @param text - The text to scan for PII.
+     */
+    detectPii(text: string): Promise<DetectPIIResult>;
+    /**
+     * Optimize text to reduce LLM token consumption while preserving meaning.
+     *
+     * @param text - The text to optimize.
+     * @param targetModel - The target model to optimize token usage for. @default 'gpt-4o'
+     * @param targetReduction - Desired reduction ratio, between 0 and 0.9. @default 0.3
+     */
+    optimizeTokens(text: string, targetModel?: TokenizerModel, targetReduction?: number): Promise<OptimizeResult>;
+    /**
+     * Count tokens for a given text and model without modifying the content.
+     *
+     * @param text - The text to count tokens for.
+     * @param model - The target model to count tokens for. @default 'gpt-4o'
+     */
+    countTokens(text: string, model?: TokenizerModel): Promise<TokenCountResult>;
+    /** Performs a POST request against the SCT API and parses the JSON response. */
+    private request;
+}
+export type { DataFormat, EncryptionMethod, TokenizerModel };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAEhB,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC;AAOpB,0EAA0E;AAC1E,qBAAa,QAAS,SAAQ,KAAK;IACjC,wEAAwE;IACxE,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,6DAA6D;IAC7D,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAOnE;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,OAAO,EAAE,gBAAgB;IASrC;;;;;OAKG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYhG;;;;;;OAMG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,oBAAoB,CAAC;IAWhC;;;;OAIG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIvD;;;;;;OAMG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,cAAwC,EACrD,eAAe,GAAE,MAAiC,GACjD,OAAO,CAAC,cAAc,CAAC;IAQ1B;;;;;OAKG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,cAAwC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI3G,gFAAgF;YAClE,OAAO;CAgCtB;AAWD,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,149 @@
+const DEFAULT_BASE_URL = 'https://sct.simosphereai.com/api/v1';
+const DEFAULT_ENCRYPTION_METHOD = 'aes-256-gcm';
+const DEFAULT_TOKENIZER_MODEL = 'gpt-4o';
+const DEFAULT_TARGET_REDUCTION = 0.3;
+/** Error thrown for any non-2xx response or network/transport failure. */
+export class SCTError extends Error {
+    /** HTTP status code, or 0 when the request never reached the server. */
+    statusCode;
+    /** Raw error payload returned by the API, when available. */
+    details;
+    constructor(message, statusCode, details) {
+        super(message);
+        this.name = 'SCTError';
+        this.statusCode = statusCode;
+        this.details = details;
+        Object.setPrototypeOf(this, SCTError.prototype);
+    }
+}
+/**
+ * Client for the SCT (Secure Compact Tokenization) API.
+ *
+ * @example
+ * ```ts
+ * const client = new SCTClient({ apiKey: process.env.SCT_API_KEY! });
+ * const result = await client.pseudonymize(
+ *   JSON.stringify({ name: 'Max Mustermann', email: 'max@example.com' }),
+ *   { format: 'json', autoDetectPii: true },
+ * );
+ * console.log(result.pseudonymized_data);
+ * ```
+ */
+export class SCTClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor(options) {
+        if (!options?.apiKey) {
+            throw new Error('SCTClient: "apiKey" is required.');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs;
+    }
+    /**
+     * Pseudonymize PII within structured or free-text data.
+     *
+     * @param data - The raw data to pseudonymize (JSON string, CSV, XML, or plain text).
+     * @param options - Format, encryption, and field-selection options.
+     */
+    async pseudonymize(data, options = {}) {
+        return this.request('/pseudonymize', {
+            data,
+            format: options.format,
+            encryption_method: options.method ?? DEFAULT_ENCRYPTION_METHOD,
+            fields: options.fields,
+            exclude_fields: options.excludeFields,
+            auto_detect_pii: options.autoDetectPii ?? false,
+            encryption_key: options.encryptionKey,
+        });
+    }
+    /**
+     * Restore data that was previously pseudonymized.
+     *
+     * @param data - The pseudonymized data to restore.
+     * @param encryptionKey - The encryption key returned by {@link pseudonymize}.
+     * @param options - Format, encryption, and field-selection options.
+     */
+    async dePseudonymize(data, encryptionKey, options = {}) {
+        return this.request('/de-pseudonymize', {
+            data,
+            encryption_key: encryptionKey,
+            format: options.format,
+            encryption_method: options.method ?? DEFAULT_ENCRYPTION_METHOD,
+            fields: options.fields,
+            exclude_fields: options.excludeFields,
+        });
+    }
+    /**
+     * Detect PII entities within free text without pseudonymizing it.
+     *
+     * @param text - The text to scan for PII.
+     */
+    async detectPii(text) {
+        return this.request('/detect-pii', { text });
+    }
+    /**
+     * Optimize text to reduce LLM token consumption while preserving meaning.
+     *
+     * @param text - The text to optimize.
+     * @param targetModel - The target model to optimize token usage for. @default 'gpt-4o'
+     * @param targetReduction - Desired reduction ratio, between 0 and 0.9. @default 0.3
+     */
+    async optimizeTokens(text, targetModel = DEFAULT_TOKENIZER_MODEL, targetReduction = DEFAULT_TARGET_REDUCTION) {
+        return this.request('/tokenizer/optimize', {
+            text,
+            model: targetModel,
+            target_reduction: targetReduction,
+        });
+    }
+    /**
+     * Count tokens for a given text and model without modifying the content.
+     *
+     * @param text - The text to count tokens for.
+     * @param model - The target model to count tokens for. @default 'gpt-4o'
+     */
+    async countTokens(text, model = DEFAULT_TOKENIZER_MODEL) {
+        return this.request('/tokenizer/count', { text, model });
+    }
+    /** Performs a POST request against the SCT API and parses the JSON response. */
+    async request(path, body) {
+        const controller = this.timeoutMs !== undefined ? new AbortController() : undefined;
+        const timer = controller && this.timeoutMs !== undefined ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
+        let response;
+        try {
+            response = await fetch(this.baseUrl + path, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(stripUndefined(body)),
+                signal: controller?.signal,
+            });
+        }
+        catch (cause) {
+            if (controller?.signal.aborted) {
+                throw new SCTError(`Request to ${path} timed out after ${this.timeoutMs}ms`, 0);
+            }
+            throw new SCTError(`Network error while requesting ${path}: ${errorMessage(cause)}`, 0);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const payload = await response.json().catch(() => ({ detail: 'Request failed' }));
+            throw new SCTError(payload.detail ?? payload.error ?? 'Unknown error', response.status, payload.details);
+        }
+        return response.json();
+    }
+}
+/** Removes `undefined` values so they are omitted from the JSON payload entirely. */
+function stripUndefined(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SCTClient, SCTError } from './client.js';
+export type { SCTClientOptions, PseudonymizeOptions, PseudonymizeResult, DePseudonymizeOptions, DePseudonymizeResult, DetectPIIResult, DetectedEntity, OptimizeResult, TokenCountResult, DataFormat, EncryptionMethod, TokenizerModel, SCTErrorPayload, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SCTClient, SCTError } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Type definitions for the SCT (Secure Compact Tokenization) API.
+ *
+ * These types mirror the response/request shapes produced by the
+ * api-gateway routes (`pseudonymize.ts`, `tokenizer.ts`) which proxy
+ * `sct-core` (pseudonymization) and the tokenizer service verbatim.
+ */
+/** Options for constructing an {@link SCTClient}. */
+export interface SCTClientOptions {
+    /** SCT API key, sent as a Bearer token. */
+    apiKey: string;
+    /**
+     * Base URL of the SCT API, including version prefix.
+     * @default 'https://sct.simosphereai.com/api/v1'
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds. When set, requests are aborted
+     * after this duration and rejected with an {@link SCTError}.
+     */
+    timeoutMs?: number;
+}
+/** Supported structured data formats for pseudonymization. */
+export type DataFormat = 'json' | 'csv' | 'xml' | 'text';
+/** Supported encryption methods. */
+export type EncryptionMethod = 'aes-256-gcm' | 'fpe-ff1';
+/** Supported tokenizer target models. */
+export type TokenizerModel = 'gpt-4' | 'gpt-4o' | 'claude-3' | 'custom';
+/** A single PII entity detected within text or structured data. */
+export interface DetectedEntity {
+    /** Entity category, e.g. "PERSON", "EMAIL", "IBAN", "PHONE". */
+    entity_type: string;
+    /** The raw matched value. */
+    value: string;
+    /** Start offset (character index) of the match within the source text. */
+    start: number;
+    /** End offset (character index, exclusive) of the match within the source text. */
+    end: number;
+    /** Detection confidence, between 0 and 1. */
+    confidence: number;
+    /** Detection source, e.g. "regex", "ner". */
+    source: string;
+}
+/** Options accepted by {@link SCTClient.pseudonymize}. */
+export interface PseudonymizeOptions {
+    /** Data format; auto-detected by the server when omitted. */
+    format?: DataFormat;
+    /** Encryption method to use. @default 'aes-256-gcm' */
+    method?: EncryptionMethod;
+    /** Restrict pseudonymization to these fields only. */
+    fields?: string[];
+    /** Exclude these fields from pseudonymization. */
+    excludeFields?: string[];
+    /** Auto-detect PII fields via NLP entity recognition. @default false */
+    autoDetectPii?: boolean;
+    /** Bring-your-own encryption key instead of letting the server generate one. */
+    encryptionKey?: string;
+}
+/** Response returned by `POST /pseudonymize`. */
+export interface PseudonymizeResult {
+    /** The pseudonymized data, in the same format as the input. */
+    pseudonymized_data: string;
+    /** Encryption key generated (or echoed back) for later de-pseudonymization. */
+    encryption_key: string;
+    /** Data format that was processed. */
+    format: DataFormat;
+    /** Encryption method that was used. */
+    encryption_method: EncryptionMethod;
+    /** Number of records processed (1 for text/JSON objects, N for CSV rows etc.). */
+    record_count: number;
+    /** Field names that were pseudonymized. */
+    fields_encrypted: string[];
+    /** PII entities detected, populated when `auto_detect_pii` was true. */
+    detected_entities: DetectedEntity[];
+    /** Server-side processing duration in milliseconds. */
+    duration_ms: number;
+    /** Size of the original payload in bytes. */
+    original_size_bytes: number;
+    /** Size of the pseudonymized payload in bytes. */
+    pseudonymized_size_bytes: number;
+}
+/** Options accepted by {@link SCTClient.dePseudonymize}. */
+export interface DePseudonymizeOptions {
+    /** Data format; auto-detected by the server when omitted. */
+    format?: DataFormat;
+    /** Encryption method that was used to pseudonymize the data. @default 'aes-256-gcm' */
+    method?: EncryptionMethod;
+    /** Restrict decryption to these fields only. */
+    fields?: string[];
+    /** Exclude these fields from decryption. */
+    excludeFields?: string[];
+}
+/** Response returned by `POST /de-pseudonymize`. */
+export interface DePseudonymizeResult {
+    /** The restored original data. */
+    original_data: string;
+    /** Data format that was processed. */
+    format: DataFormat;
+    /** Number of records processed. */
+    record_count: number;
+    /** Server-side processing duration in milliseconds. */
+    duration_ms: number;
+}
+/** Response returned by `POST /detect-pii`. */
+export interface DetectPIIResult {
+    /** PII entities detected in the given text. */
+    entities: DetectedEntity[];
+    /** Server-side processing duration in milliseconds. */
+    duration_ms: number;
+}
+/** Response returned by `POST /tokenizer/optimize`. */
+export interface OptimizeResult {
+    /** The optimized text, semantically equivalent but with fewer tokens. */
+    optimized_text: string;
+    /** Token count of the original text. */
+    original_tokens: number;
+    /** Token count of the optimized text. */
+    optimized_tokens: number;
+    /** Number of tokens saved (original_tokens - optimized_tokens). */
+    tokens_saved: number;
+    /** Reduction percentage, e.g. 30.9 for a ~31% reduction. */
+    reduction_percent: number;
+    /** Target model the token count was computed against. */
+    model: TokenizerModel;
+}
+/** Response returned by `POST /tokenizer/count`. */
+export interface TokenCountResult {
+    /** Number of tokens in the given text for the given model. */
+    token_count: number;
+    /** Target model the token count was computed against. */
+    model: TokenizerModel;
+}
+/** Shape of an error payload returned by the SCT API. */
+export interface SCTErrorPayload {
+    error?: string;
+    detail?: string;
+    details?: unknown;
+}
+//# 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/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the SCT (Secure Compact Tokenization) API.
+ *
+ * These types mirror the response/request shapes produced by the
+ * api-gateway routes (`pseudonymize.ts`, `tokenizer.ts`) which proxy
+ * `sct-core` (pseudonymization) and the tokenizer service verbatim.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "sct-client",
+  "version": "0.1.0",
+  "description": "Official Node.js/TypeScript SDK for the SCT (Secure Compact Tokenization) API \u2014 pseudonymize PII, stream encrypted data, and optimize LLM tokens.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "sct",
+    "pseudonymization",
+    "pii",
+    "tokenizer",
+    "encryption",
+    "gdpr",
+    "dsgvo",
+    "llm"
+  ],
+  "author": "SIMO GmbH",
+  "license": "UNLICENSED",
+  "homepage": "https://sct.simosphereai.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.simo-online.com/simosphereos/secure-compact-tokenization.git",
+    "directory": "sdks/node"
+  },
+  "bugs": {
+    "url": "https://gitlab.simo-online.com/simosphereos/secure-compact-tokenization/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  }
+}