@cipherstash/stack 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -33,8 +33,8 @@ __export(index_exports, {
   Encryption: () => Encryption,
   EncryptionErrorTypes: () => EncryptionErrorTypes,
   encryptedColumn: () => encryptedColumn,
+  encryptedField: () => encryptedField,
   encryptedTable: () => encryptedTable,
-  encryptedValue: () => encryptedValue,
   getErrorMessage: () => getErrorMessage
 });
 module.exports = __toCommonJS(index_exports);
@@ -98,7 +98,7 @@ var encryptConfigSchema = import_zod.z.object({
   v: import_zod.z.number(),
   tables: tablesSchema
 });
-var ProtectValue = class {
+var EncryptedField = class {
   valueName;
   castAsValue;
   constructor(valueName) {
@@ -106,20 +106,20 @@ var ProtectValue = class {
     this.castAsValue = "string";
   }
   /**
-   * Set or override the plaintext data type for this value.
+   * Set or override the plaintext data type for this field.
    *
    * By default all values are treated as `'string'`. Use this method to specify
    * a different type so the encryption layer knows how to encode the plaintext
    * before encrypting.
    *
    * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, or `'json'`.
-   * @returns This `ProtectValue` instance for method chaining.
+   * @returns This `EncryptedField` instance for method chaining.
    *
    * @example
    * ```typescript
-   * import { encryptedValue } from "@cipherstash/stack/schema"
+   * import { encryptedField } from "@cipherstash/stack/schema"
    *
-   * const age = encryptedValue("age").dataType("number")
+   * const age = encryptedField("age").dataType("number")
    * ```
    */
   dataType(castAs) {
@@ -136,7 +136,7 @@ var ProtectValue = class {
     return this.valueName;
   }
 };
-var ProtectColumn = class {
+var EncryptedColumn = class {
   columnName;
   castAsValue;
   indexesValue = {};
@@ -152,7 +152,7 @@ var ProtectColumn = class {
    * before encrypting.
    *
    * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, or `'json'`.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -171,7 +171,7 @@ var ProtectColumn = class {
    * ORE allows sorting, comparison, and range queries on encrypted data.
    * Use with `encryptQuery` and `queryType: 'orderAndRange'`.
    *
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -194,7 +194,7 @@ var ProtectColumn = class {
    *
    * @param tokenFilters - Optional array of token filters (e.g. `[{ kind: 'downcase' }]`).
    *   When omitted, no token filters are applied.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -219,7 +219,7 @@ var ProtectColumn = class {
    *
    * @param opts - Optional match index configuration. Defaults to 3-character ngram
    *   tokenization with a downcase filter, `k=6`, `m=2048`, and `include_original=true`.
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -264,7 +264,7 @@ var ProtectColumn = class {
    * the plaintext type: strings become selector queries, objects/arrays become
    * containment queries.
    *
-   * @returns This `ProtectColumn` instance for method chaining.
+   * @returns This `EncryptedColumn` instance for method chaining.
    *
    * @example
    * ```typescript
@@ -290,7 +290,7 @@ var ProtectColumn = class {
     return this.columnName;
   }
 };
-var ProtectTable = class {
+var EncryptedTable = class {
   constructor(tableName, columnBuilders) {
     this.tableName = tableName;
     this.columnBuilders = columnBuilders;
@@ -317,7 +317,7 @@ var ProtectTable = class {
   build() {
     const builtColumns = {};
     const processColumn = (builder, colName) => {
-      if (builder instanceof ProtectColumn) {
+      if (builder instanceof EncryptedColumn) {
         const builtColumn = builder.build();
         if (builtColumn.cast_as === "json" && builtColumn.indexes.ste_vec?.prefix === "enabled") {
           builtColumns[colName] = {
@@ -334,7 +334,7 @@ var ProtectTable = class {
         }
       } else {
         for (const [key, value] of Object.entries(builder)) {
-          if (value instanceof ProtectValue) {
+          if (value instanceof EncryptedField) {
             builtColumns[value.getName()] = value.build();
           } else {
             processColumn(value, key);
@@ -352,7 +352,10 @@ var ProtectTable = class {
   }
 };
 function encryptedTable(tableName, columns) {
-  const tableBuilder = new ProtectTable(tableName, columns);
+  const tableBuilder = new EncryptedTable(
+    tableName,
+    columns
+  );
   for (const [colName, colBuilder] of Object.entries(columns)) {
     ;
     tableBuilder[colName] = colBuilder;
@@ -360,10 +363,10 @@ function encryptedTable(tableName, columns) {
   return tableBuilder;
 }
 function encryptedColumn(columnName) {
-  return new ProtectColumn(columnName);
+  return new EncryptedColumn(columnName);
 }
-function encryptedValue(valueName) {
-  return new ProtectValue(valueName);
+function encryptedField(valueName) {
+  return new EncryptedField(valueName);
 }
 function buildEncryptConfig(...protectTables) {
   const config = {
@@ -457,7 +460,7 @@ function initStackLogger(config) {
   const rates = samplingFromEnv();
   (0, import_evlog.initLogger)({
     env: { service: "@cipherstash/stack" },
-    enabled: config?.enabled ?? true,
+    enabled: config?.enabled ?? !!rates,
     pretty: config?.pretty,
     ...rates && { sampling: { rates } },
     ...config?.drain && { drain: config.drain }
@@ -470,7 +473,11 @@ function safeMessage(args) {
 var logger = {
   debug(...args) {
     const log = (0, import_evlog.createRequestLogger)();
-    log.set({ level: "debug", source: "@cipherstash/stack", message: safeMessage(args) });
+    log.set({
+      level: "debug",
+      source: "@cipherstash/stack",
+      message: safeMessage(args)
+    });
     log.emit();
   },
   info(...args) {
@@ -491,7 +498,7 @@ var logger = {
   }
 };
 
-// src/encryption/ffi/index.ts
+// src/encryption/index.ts
 var import_result11 = require("@byteslice/result");
 var import_protect_ffi9 = require("@cipherstash/protect-ffi");
 
@@ -534,18 +541,18 @@ function isEncryptedPayload(value) {
   return true;
 }
 
-// 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
 var import_protect_ffi = require("@cipherstash/protect-ffi");
 function getErrorCode(error) {
   return error instanceof import_protect_ffi.ProtectError ? error.code : void 0;
 }
 
-// src/encryption/ffi/operations/batch-encrypt-query.ts
+// src/encryption/operations/batch-encrypt-query.ts
 var import_result = require("@byteslice/result");
 var import_protect_ffi2 = require("@cipherstash/protect-ffi");
 
@@ -563,7 +570,7 @@ var queryTypeToQueryOp = {
   steVecTerm: "ste_vec_term"
 };
 
-// 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;
@@ -623,7 +630,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 {
@@ -659,7 +666,7 @@ function assertValueIndexCompatibility(value, indexType, columnName) {
   }
 }
 
-// src/encryption/ffi/operations/base-operation.ts
+// src/encryption/operations/base-operation.ts
 var EncryptionOperation = class {
   auditMetadata;
   /**
@@ -687,7 +694,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 = [];
@@ -842,7 +849,7 @@ var BatchEncryptQueryOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt.ts
+// src/encryption/operations/bulk-decrypt.ts
 var import_result2 = require("@byteslice/result");
 var import_protect_ffi3 = require("@cipherstash/protect-ffi");
 var createDecryptPayloads = (encryptedPayloads, lockContext) => {
@@ -993,10 +1000,10 @@ var BulkDecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-decrypt-models.ts
+// src/encryption/operations/bulk-decrypt-models.ts
 var import_result3 = require("@byteslice/result");
 
-// src/encryption/ffi/model-helpers.ts
+// src/encryption/helpers/model-helpers.ts
 var import_protect_ffi4 = require("@cipherstash/protect-ffi");
 function setNestedValue(obj, path2, value) {
   const FORBIDDEN_KEYS = ["__proto__", "prototype", "constructor"];
@@ -1511,7 +1518,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;
@@ -1608,7 +1615,7 @@ var BulkDecryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt.ts
+// src/encryption/operations/bulk-encrypt.ts
 var import_result4 = require("@byteslice/result");
 var import_protect_ffi5 = require("@cipherstash/protect-ffi");
 var createEncryptPayloads = (plaintexts, column, table, lockContext) => {
@@ -1773,7 +1780,7 @@ var BulkEncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/bulk-encrypt-models.ts
+// src/encryption/operations/bulk-encrypt-models.ts
 var import_result5 = require("@byteslice/result");
 var BulkEncryptModelsOperation = class extends EncryptionOperation {
   client;
@@ -1882,7 +1889,7 @@ var BulkEncryptModelsOperationWithLockContext = class extends EncryptionOperatio
   }
 };
 
-// src/encryption/ffi/operations/decrypt.ts
+// src/encryption/operations/decrypt.ts
 var import_result6 = require("@byteslice/result");
 var import_protect_ffi6 = require("@cipherstash/protect-ffi");
 var DecryptOperation = class extends EncryptionOperation {
@@ -1989,7 +1996,7 @@ var DecryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/decrypt-model.ts
+// src/encryption/operations/decrypt-model.ts
 var import_result7 = require("@byteslice/result");
 var DecryptModelOperation = class extends EncryptionOperation {
   client;
@@ -2085,7 +2092,7 @@ var DecryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt.ts
+// src/encryption/operations/encrypt.ts
 var import_result8 = require("@byteslice/result");
 var import_protect_ffi7 = require("@cipherstash/protect-ffi");
 var EncryptOperation = class extends EncryptionOperation {
@@ -2211,7 +2218,7 @@ var EncryptOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-model.ts
+// src/encryption/operations/encrypt-model.ts
 var import_result9 = require("@byteslice/result");
 var EncryptModelOperation = class extends EncryptionOperation {
   client;
@@ -2318,7 +2325,7 @@ var EncryptModelOperationWithLockContext = class extends EncryptionOperation {
   }
 };
 
-// src/encryption/ffi/operations/encrypt-query.ts
+// src/encryption/operations/encrypt-query.ts
 var import_result10 = require("@byteslice/result");
 var import_protect_ffi8 = require("@cipherstash/protect-ffi");
 var EncryptQueryOperation = class extends EncryptionOperation {
@@ -2468,9 +2475,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;
@@ -2493,7 +2500,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
           }
@@ -2501,15 +2508,15 @@ var EncryptionClient = class {
         this.client = await (0, import_protect_ffi9.newClient)({
           encryptConfig: validated,
           clientOpts: {
-            workspaceCrn: config.workspaceCrn,
-            accessKey: config.accessKey,
-            clientId: config.clientId,
-            clientKey: config.clientKey,
+            workspaceCrn: config.workspaceCrn ?? process.env.CS_WORKSPACE_CRN,
+            accessKey: config.accessKey ?? process.env.CS_CLIENT_ACCESS_KEY,
+            clientId: config.clientId ?? process.env.CS_CLIENT_ID,
+            clientKey: config.clientKey ?? process.env.CS_CLIENT_KEY,
             keyset: toFfiKeysetIdentifier(config.keyset)
           }
         });
         this.encryptConfig = validated;
-        logger.debug("Successfully initialized the Protect.js client.");
+        logger.debug("Successfully initialized the Encryption client.");
         return this;
       },
       (error) => ({
@@ -2522,7 +2529,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
@@ -2585,8 +2592,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}
    */
@@ -2654,10 +2664,16 @@ var EncryptionClient = class {
    * All other fields are passed through unchanged. Returns a thenable operation
    * that supports `.withLockContext()` for identity-aware encryption.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments
+   * rather than providing an explicit type argument.
+   *
    * @param input - The model object with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns An `EncryptModelOperation<T>` that can be awaited to get a `Result`
-   *   containing the model with encrypted fields, or an `EncryptionError`.
+   * @returns An `EncryptModelOperation` that can be awaited to get a `Result`
+   *   containing the model with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -2672,7 +2688,9 @@ var EncryptionClient = class {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.encryptModel<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // result.data.email is typed as `Encrypted`, result.data.id stays `string`.
+   * const result = await client.encryptModel(
    *   { id: "user_123", email: "alice@example.com", createdAt: new Date() },
    *   usersSchema,
    * )
@@ -2680,13 +2698,17 @@ var EncryptionClient = class {
    * if (result.failure) {
    *   console.error(result.failure.message)
    * } else {
-   *   // result.data.id is unchanged, result.data.email is encrypted
-   *   console.log(result.data)
+   *   console.log(result.data.id)    // string
+   *   console.log(result.data.email) // Encrypted
    * }
    * ```
    */
   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.
@@ -2726,10 +2748,15 @@ var EncryptionClient = class {
    * while still using a unique key for each encrypted value. Only fields
    * matching the table schema are encrypted; other fields pass through unchanged.
    *
+   * The return type is **schema-aware**: fields matching the table schema are
+   * typed as `Encrypted`, while other fields retain their original types. For
+   * best results, let TypeScript infer the type parameters from the arguments.
+   *
    * @param input - An array of model objects with plaintext values to encrypt.
    * @param table - The table schema defining which fields to encrypt.
-   * @returns A `BulkEncryptModelsOperation<T>` that can be awaited to get a `Result`
-   *   containing an array of models with encrypted fields, or an `EncryptionError`.
+   * @returns A `BulkEncryptModelsOperation` that can be awaited to get a `Result`
+   *   containing an array of models with schema-defined fields typed as `Encrypted`,
+   *   or an `EncryptionError`.
    *
    * @example
    * ```typescript
@@ -2744,7 +2771,9 @@ var EncryptionClient = class {
    *
    * const client = await Encryption({ schemas: [usersSchema] })
    *
-   * const result = await client.bulkEncryptModels<User>(
+   * // Let TypeScript infer the return type from the schema.
+   * // Each item's email is typed as `Encrypted`, id stays `string`.
+   * const result = await client.bulkEncryptModels(
    *   [
    *     { id: "1", email: "alice@example.com" },
    *     { id: "2", email: "bob@example.com" },
@@ -2758,7 +2787,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.
@@ -2799,7 +2832,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`.
    *
@@ -2908,8 +2941,8 @@ var Encryption = async (config) => {
   Encryption,
   EncryptionErrorTypes,
   encryptedColumn,
+  encryptedField,
   encryptedTable,
-  encryptedValue,
   getErrorMessage
 });
 //# sourceMappingURL=index.cjs.map