@cipherstash/stack 0.2.0 → 0.3.0

package/dist/{chunk-5G4F4JJG.js → chunk-JLI27P46.js}

@@ -25,4 +25,4 @@ export {
   queryTypeToFfi,
   queryTypeToQueryOp
 };
-//# sourceMappingURL=chunk-5G4F4JJG.js.map
+//# sourceMappingURL=chunk-JLI27P46.js.map

package/dist/chunk-JLI27P46.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type {\n  EncryptedColumn,\n  EncryptedTable,\n  EncryptedTableColumn,\n  EncryptedField,\n} from '@/schema'\nimport type { LoggingConfig } from '@/utils/logger'\nimport type {\n  Encrypted as CipherStashEncrypted,\n  JsPlaintext,\n  QueryOpName,\n  newClient,\n} from '@cipherstash/protect-ffi'\n\n// ---------------------------------------------------------------------------\n// Branded type utilities\n// ---------------------------------------------------------------------------\n\n/** Brand symbol for nominal typing */\ndeclare const __brand: unique symbol\n\n/** Creates a branded type that is structurally incompatible with the base type */\ntype Brand<T, B extends string> = T & { readonly [__brand]: B }\n\n// ---------------------------------------------------------------------------\n// Core types\n// ---------------------------------------------------------------------------\n\nexport type Client = Awaited<ReturnType<typeof newClient>> | undefined\n\n/** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */\nexport type EncryptedValue = Brand<CipherStashEncrypted, 'encrypted'> | null\n\n/** Structural type representing encrypted data. See also `EncryptedValue` for branded nominal typing. */\nexport type Encrypted = CipherStashEncrypted | null\n\nexport type EncryptPayload = JsPlaintext | null\n\n// ---------------------------------------------------------------------------\n// Client configuration\n// ---------------------------------------------------------------------------\n\nexport type KeysetIdentifier = { name: string } | { id: string }\n\nexport type ClientConfig = {\n  /**\n   * The CipherStash workspace CRN (Cloud Resource Name).\n   * Format: `crn:<region>.aws:<workspace-id>`.\n   * Can also be set via the `CS_WORKSPACE_CRN` environment variable.\n   * If omitted, the SDK reads from the environment or TOML config files.\n   */\n  workspaceCrn?: string\n\n  /**\n   * The API access key used for authenticating with the CipherStash API.\n   * Can also be set via the `CS_CLIENT_ACCESS_KEY` environment variable.\n   * Obtain this from the CipherStash dashboard after creating a workspace.\n   */\n  accessKey?: string\n\n  /**\n   * The client identifier used to authenticate with CipherStash services.\n   * Can also be set via the `CS_CLIENT_ID` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientId?: string\n\n  /**\n   * The client key material used in combination with ZeroKMS for encryption operations.\n   * Can also be set via the `CS_CLIENT_KEY` environment variable.\n   * Generated during workspace onboarding in the CipherStash dashboard.\n   */\n  clientKey?: string\n\n  /**\n   * An optional keyset identifier for multi-tenant encryption.\n   * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.\n   * Specify by name (`{ name: \"tenant-a\" }`) or UUID (`{ id: \"...\" }`).\n   * Keysets are created and managed in the CipherStash dashboard.\n   */\n  keyset?: KeysetIdentifier\n}\n\ntype AtLeastOneCsTable<T> = [T, ...T[]]\n\nexport type EncryptionClientConfig = {\n  schemas: AtLeastOneCsTable<EncryptedTable<EncryptedTableColumn>>\n  config?: ClientConfig\n  logging?: LoggingConfig\n}\n\n// ---------------------------------------------------------------------------\n// Encrypt / decrypt operation options and results\n// ---------------------------------------------------------------------------\n\n/**\n * Options for single-value encrypt operations.\n * Use a column from your table schema (from {@link encryptedColumn}) or a nested\n * field (from {@link encryptedField}) as the target for encryption.\n */\nexport type EncryptOptions = {\n  /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */\n  column: EncryptedColumn | EncryptedField\n  table: EncryptedTable<EncryptedTableColumn>\n}\n\n/** Format for encrypted query/search term return values */\nexport type EncryptedReturnType =\n  | 'eql'\n  | 'composite-literal'\n  | 'escaped-composite-literal'\n\nexport type SearchTerm = {\n  value: JsPlaintext\n  column: EncryptedColumn\n  table: EncryptedTable<EncryptedTableColumn>\n  returnType?: EncryptedReturnType\n}\n\n/** Encrypted search term result: EQL object or composite literal string */\nexport type EncryptedSearchTerm = Encrypted | string\n\n/** Result of encryptQuery (single or batch): EQL, composite literal string, or null */\nexport type EncryptedQueryResult = Encrypted | string | null\n\n// ---------------------------------------------------------------------------\n// Model field types (encrypted vs decrypted views)\n// ---------------------------------------------------------------------------\n\nexport type EncryptedFields<T> = {\n  [K in keyof T as T[K] extends Encrypted ? K : never]: T[K]\n}\n\nexport type OtherFields<T> = {\n  [K in keyof T as T[K] extends Encrypted ? never : K]: T[K]\n}\n\nexport type DecryptedFields<T> = {\n  [K in keyof T as T[K] extends Encrypted ? K : never]: string\n}\n\n/** Model with encrypted fields replaced by plaintext (decrypted) values */\nexport type Decrypted<T> = OtherFields<T> & DecryptedFields<T>\n\n/**\n * Maps a plaintext model type to its encrypted form using the table schema.\n *\n * Fields whose keys match columns defined in `S` become `Encrypted`;\n * all other fields retain their original types from `T`.\n *\n * When `S` is the widened `EncryptedTableColumn` (e.g. when a user passes an\n * explicit `<User>` type argument without specifying `S`), the type degrades\n * gracefully to `T` — preserving backward compatibility.\n *\n * @typeParam T - The plaintext model type (e.g. `{ id: string; email: string }`)\n * @typeParam S - The table schema column definition, inferred from the `table` argument\n *\n * @example\n * ```typescript\n * type User = { id: string; email: string }\n * // With a schema that defines `email`:\n * type Encrypted = EncryptedFromSchema<User, { email: EncryptedColumn }>\n * // => { id: string; email: Encrypted }\n * ```\n */\nexport type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {\n  [K in keyof T]: [K] extends [keyof S]\n    ? [S[K & keyof S]] extends [EncryptedColumn | EncryptedField]\n      ? Encrypted\n      : T[K]\n    : T[K]\n}\n\n// ---------------------------------------------------------------------------\n// Bulk operations\n// ---------------------------------------------------------------------------\n\nexport type BulkEncryptPayload = Array<{\n  id?: string\n  plaintext: JsPlaintext | null\n}>\n\nexport type BulkEncryptedData = Array<{ id?: string; data: Encrypted }>\nexport type BulkDecryptPayload = Array<{ id?: string; data: Encrypted }>\nexport type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>\n\ntype DecryptionSuccess<T> = { error?: never; data: T; id?: string }\ntype DecryptionError<T> = { error: T; id?: string; data?: never }\n\n/**\n * Result type for individual items in bulk decrypt operations.\n * Uses `error`/`data` fields (not `failure`/`data`) since bulk operations\n * can have per-item failures.\n */\nexport type DecryptionResult<T> = DecryptionSuccess<T> | DecryptionError<T>\n\n// ---------------------------------------------------------------------------\n// Query types (for searchable encryption / encryptQuery)\n// ---------------------------------------------------------------------------\n\n/**\n * User-facing query type names for encrypting query values.\n *\n * - `'equality'`: Exact match. [Exact Queries](https://cipherstash.com/docs/platform/searchable-encryption/supported-queries/exact)\n * - `'freeTextSearch'`: Text search. [Match Queries](https://cipherstash.com/docs/platform/searchable-encryption/supported-queries/match)\n * - `'orderAndRange'`: Comparison and range. [Range Queries](https://cipherstash.com/docs/platform/searchable-encryption/supported-queries/range)\n * - `'steVecSelector'`: JSONPath selector (e.g. `'$.user.email'`)\n * - `'steVecTerm'`: Containment (e.g. `{ role: 'admin' }`)\n * - `'searchableJson'`: Auto-infers selector or term from plaintext type (recommended)\n */\nexport type QueryTypeName =\n  | 'orderAndRange'\n  | 'freeTextSearch'\n  | 'equality'\n  | 'steVecSelector'\n  | 'steVecTerm'\n  | 'searchableJson'\n\n/** @internal */\nexport type FfiIndexTypeName = 'ore' | 'match' | 'unique' | 'ste_vec'\n\nexport const queryTypes = {\n  orderAndRange: 'orderAndRange',\n  freeTextSearch: 'freeTextSearch',\n  equality: 'equality',\n  steVecSelector: 'steVecSelector',\n  steVecTerm: 'steVecTerm',\n  searchableJson: 'searchableJson',\n} as const satisfies Record<string, QueryTypeName>\n\n/** @internal */\nexport const queryTypeToFfi: Record<QueryTypeName, FfiIndexTypeName> = {\n  orderAndRange: 'ore',\n  freeTextSearch: 'match',\n  equality: 'unique',\n  steVecSelector: 'ste_vec',\n  steVecTerm: 'ste_vec',\n  searchableJson: 'ste_vec',\n}\n\n/** @internal */\nexport const queryTypeToQueryOp: Partial<Record<QueryTypeName, QueryOpName>> = {\n  steVecSelector: 'ste_vec_selector',\n  steVecTerm: 'ste_vec_term',\n}\n\n/** @internal */\nexport type QueryTermBase = {\n  column: EncryptedColumn\n  table: EncryptedTable<EncryptedTableColumn>\n  queryType?: QueryTypeName\n  returnType?: EncryptedReturnType\n}\n\nexport type EncryptQueryOptions = QueryTermBase\n\nexport type ScalarQueryTerm = QueryTermBase & {\n  value: JsPlaintext | null\n}\n"],"mappings":";AA6NO,IAAM,aAAa;AAAA,EACxB,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ,gBAAgB;AAClB;AAGO,IAAM,iBAA0D;AAAA,EACrE,eAAe;AAAA,EACf,gBAAgB;AAAA,EAChB,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,YAAY;AAAA,EACZ,gBAAgB;AAClB;AAGO,IAAM,qBAAkE;AAAA,EAC7E,gBAAgB;AAAA,EAChB,YAAY;AACd;","names":[]}

package/dist/{chunk-LHZ6KZIG.js → chunk-MW6D52V2.js}

@@ -6,29 +6,29 @@ import {
 import {
   queryTypeToFfi,
   queryTypeToQueryOp
-} from "./chunk-5G4F4JJG.js";
+} from "./chunk-JLI27P46.js";
 import {
   EncryptionErrorTypes,
   createRequestLogger,
   initStackLogger,
   loadWorkSpaceId,
   logger
-} from "./chunk-5DCT6YU2.js";
+} from "./chunk-OAPLZLR5.js";
 import {
   buildEncryptConfig,
   encryptConfigSchema
-} from "./chunk-7XRPN2KX.js";
+} from "./chunk-TBAIVO6T.js";
 
-// src/encryption/ffi/index.ts
+// src/encryption/index.ts
 import { withResult as withResult11 } from "@byteslice/result";
 import { newClient } from "@cipherstash/protect-ffi";
 
-// src/encryption/ffi/helpers/type-guards.ts
+// src/encryption/helpers/type-guards.ts
 function isScalarQueryTermArray(value) {
   return Array.isArray(value) && value.length > 0 && typeof value[0] === "object" && value[0] !== null && "column" in value[0] && "table" in value[0];
 }
 
-// src/encryption/ffi/helpers/error-code.ts
+// src/encryption/helpers/error-code.ts
 import {
   ProtectError as FfiProtectError
 } from "@cipherstash/protect-ffi";
@@ -36,13 +36,13 @@ function getErrorCode(error) {
   return error instanceof FfiProtectError ? error.code : void 0;
 }
 
-// src/encryption/ffi/operations/batch-encrypt-query.ts
+// src/encryption/operations/batch-encrypt-query.ts
 import { withResult } from "@byteslice/result";
 import {
   encryptQueryBulk as ffiEncryptQueryBulk
 } from "@cipherstash/protect-ffi";
 
-// src/encryption/ffi/helpers/infer-index-type.ts
+// src/encryption/helpers/infer-index-type.ts
 function inferIndexType(column) {
   const config = column.build();
   const indexes = config.indexes;
@@ -102,7 +102,7 @@ function resolveIndexType(column, queryType, plaintext) {
   return { indexType };
 }
 
-// src/encryption/ffi/helpers/validation.ts
+// src/encryption/helpers/validation.ts
 function validateNumericValue(value) {
   if (typeof value === "number" && Number.isNaN(value)) {
     return {
@@ -138,7 +138,7 @@ function assertValueIndexCompatibility(value, indexType, columnName) {
   }
 }
 
-// src/encryption/ffi/operations/base-operation.ts
+// src/encryption/operations/base-operation.ts
 var EncryptionOperation = class {
   auditMetadata;
   /**
@@ -166,7 +166,7 @@ var EncryptionOperation = class {
   }
 };
 
-// src/encryption/ffi/operations/batch-encrypt-query.ts
+// src/encryption/operations/batch-encrypt-query.ts
 function filterNullTerms(terms) {
   const nullIndices = /* @__PURE__ */ new Set();
   const nonNullTerms = [];
@@ -321,7 +321,7 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt.ts
+// src/encryption/operations/bulk-decrypt.ts
 import { withResult as withResult2 } from "@byteslice/result";
 import {
   decryptBulkFallible
@@ -474,10 +474,10 @@ var BulkDecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt-models.ts
+// src/encryption/operations/bulk-decrypt-models.ts
 import { withResult as withResult3 } from "@byteslice/result";
 
-// src/encryption/ffi/model-helpers.ts
+// src/encryption/helpers/model-helpers.ts
 import {
   decryptBulk,
   encryptBulk
@@ -995,7 +995,7 @@ async function bulkEncryptModelsWithLockContext(models, table, client, lockConte
   });
 }
 
-// src/encryption/ffi/operations/bulk-decrypt-models.ts
+// src/encryption/operations/bulk-decrypt-models.ts
 var BulkDecryptModelsOperation = class extends EncryptionOperation {
   client;
   models;
@@ -1092,7 +1092,7 @@ var BulkDecryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt.ts
+// src/encryption/operations/bulk-encrypt.ts
 import { withResult as withResult4 } from "@byteslice/result";
 import { encryptBulk as encryptBulk2 } from "@cipherstash/protect-ffi";
 var createEncryptPayloads = (plaintexts, column, table, lockContext) => {
@@ -1257,7 +1257,7 @@ var BulkEncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt-models.ts
+// src/encryption/operations/bulk-encrypt-models.ts
 import { withResult as withResult5 } from "@byteslice/result";
 var BulkEncryptModelsOperation = class extends EncryptionOperation {
   client;
@@ -1366,7 +1366,7 @@ var BulkEncryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/decrypt.ts
+// src/encryption/operations/decrypt.ts
 import { withResult as withResult6 } from "@byteslice/result";
 import {
   decrypt as ffiDecrypt
@@ -1475,7 +1475,7 @@ var DecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/decrypt-model.ts
+// src/encryption/operations/decrypt-model.ts
 import { withResult as withResult7 } from "@byteslice/result";
 var DecryptModelOperation = class extends EncryptionOperation {
   client;
@@ -1571,7 +1571,7 @@ var DecryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt.ts
+// src/encryption/operations/encrypt.ts
 import { withResult as withResult8 } from "@byteslice/result";
 import {
   encrypt as ffiEncrypt
@@ -1699,7 +1699,7 @@ var EncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-model.ts
+// src/encryption/operations/encrypt-model.ts
 import { withResult as withResult9 } from "@byteslice/result";
 var EncryptModelOperation = class extends EncryptionOperation {
   client;
@@ -1806,7 +1806,7 @@ var EncryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-query.ts
+// src/encryption/operations/encrypt-query.ts
 import { withResult as withResult10 } from "@byteslice/result";
 import {
   encryptQuery as ffiEncryptQuery
@@ -1958,9 +1958,9 @@ var EncryptQueryOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/index.ts
+// src/encryption/index.ts
 var noClientError = () => new Error(
-  "The EQL client has not been initialized. Please call init() before using the client."
+  "The Encryption client has not been initialized. Please call init() before using the client."
 );
 var EncryptionClient = class {
   client;
@@ -1983,7 +1983,7 @@ var EncryptionClient = class {
           config.encryptConfig
         );
         logger.debug(
-          "Initializing the Protect.js client with the following encrypt config:",
+          "Initializing the Encryption client with the following config:",
           {
             encryptConfig: validated
           }
@@ -1999,7 +1999,7 @@ var EncryptionClient = class {
           }
         });
         this.encryptConfig = validated;
-        logger.debug("Successfully initialized the Protect.js client.");
+        logger.debug("Successfully initialized the Encryption client.");
         return this;
       },
       (error) => ({
@@ -2012,7 +2012,7 @@ var EncryptionClient = class {
    * Encrypt a value - returns a promise which resolves to an encrypted value.
    *
    * @param plaintext - The plaintext value to be encrypted. Can be null.
-   * @param opts - Options specifying the column and table for encryption.
+   * @param opts - Options specifying the column (or nested field) and table for encryption. See {@link EncryptOptions}.
    * @returns An EncryptOperation that can be awaited or chained with additional methods.
    *
    * @example
@@ -2075,8 +2075,11 @@ var EncryptionClient = class {
    *  .withLockContext(lockContext)
    * ```
    *
+   * @see {@link EncryptOptions}
    * @see {@link Result}
    * @see {@link encryptedTable}
+   * @see {@link encryptedColumn}
+   * @see {@link encryptedField}
    * @see {@link LockContext}
    * @see {@link EncryptOperation}
    */
@@ -2184,7 +2187,11 @@ var EncryptionClient = class {
    * ```
    */
   encryptModel(input, table) {
-    return new EncryptModelOperation(this.client, input, table);
+    return new EncryptModelOperation(
+      this.client,
+      input,
+      table
+    );
   }
   /**
    * Decrypt a model (object) whose fields contain encrypted values.
@@ -2263,7 +2270,11 @@ var EncryptionClient = class {
    * ```
    */
   bulkEncryptModels(input, table) {
-    return new BulkEncryptModelsOperation(this.client, input, table);
+    return new BulkEncryptModelsOperation(
+      this.client,
+      input,
+      table
+    );
   }
   /**
    * Decrypt multiple models (objects) in a single bulk operation.
@@ -2304,7 +2315,7 @@ var EncryptionClient = class {
    * your application data. Null plaintext values are preserved as null.
    *
    * @param plaintexts - An array of objects with `plaintext` (and optional `id`) fields.
-   * @param opts - Options specifying the target column and table for encryption.
+   * @param opts - Options specifying the target column (or nested {@link encryptedField}) and table. See {@link EncryptOptions}.
    * @returns A `BulkEncryptOperation` that can be awaited to get a `Result`
    *   containing an array of `{ id?, data: Encrypted }` objects, or an `EncryptionError`.
    *
@@ -2412,4 +2423,4 @@ var Encryption = async (config) => {
 export {
   Encryption
 };
-//# sourceMappingURL=chunk-LHZ6KZIG.js.map
+//# sourceMappingURL=chunk-MW6D52V2.js.map