@cipherstash/stack 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @cipherstash/stack
 
+## 0.5.0
+
+### Minor Changes
+
+- a645115: ### Documentation
+
+  - **TypeDoc**: Improved JSDoc for `Encryption()`, `EncryptOptions`, schema builders (`encryptedTable`, `encryptedColumn`, `encryptedField`, `EncryptedField`, `EncryptedTableColumn`), and `encrypt` / `bulkEncrypt` with clearer `@param`, `@returns`, `@throws`, `@example`, and `@see` links.
+  - **README**: Refreshed main repo README and Stack package readme; basic example README now uses `npm install @cipherstash/stack`, CipherStash account and dashboard credentials, and drops Stash CLI references. Added docs badge linking to cipherstash.com/docs.
+
+  ### Features
+
+  - **Logging**: Logger is now used consistently across Stack client interfaces for initialization and operations.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -502,48 +502,21 @@ const client2 = await Encryption({
 
 ### Logging
 
-The SDK uses [evlog](https://github.com/HugoRCD/evlog) for structured logging. Each encryption operation emits a single wide event with context such as the operation type, table, column, lock context status, and duration.
+The SDK uses structured logging across all interfaces (Encryption, Secrets, Supabase, DynamoDB). Each operation emits a single wide event with context such as the operation type, table, column, lock context status, and duration.
 
-#### Environment variable
+Configure the log level with the `STASH_STACK_LOG` environment variable:
 
 ```bash
-STASH_LOG_LEVEL=debug  # debug | info | warn | error (default: info)
+STASH_STACK_LOG=error  # debug | info | error (default: error)
 ```
 
-#### Programmatic configuration
+| Value   | What is logged         |
+| ------- | ---------------------- |
+| `error` | Errors only (default)  |
+| `info`  | Info and errors        |
+| `debug` | Debug, info, and errors |
 
-Pass a `logging` option when initializing the client:
-
-```typescript
-const client = await Encryption({
-  schemas: [users],
-  logging: {
-    enabled: true,     // toggle logging on/off (default: true)
-    pretty: true,      // pretty-print in development (default: auto-detected)
-  },
-})
-```
-
-#### Log draining
-
-Send structured logs to an external observability platform by providing a `drain` callback:
-
-```typescript
-import { Encryption } from "@cipherstash/stack"
-
-const client = await Encryption({
-  schemas: [users],
-  logging: {
-    drain: (ctx) => {
-      // Forward to Axiom, Datadog, OTLP, etc.
-      fetch("https://your-service.com/logs", {
-        method: "POST",
-        body: JSON.stringify(ctx.event),
-      })
-    },
-  },
-})
-```
+When `STASH_STACK_LOG` is not set, the SDK defaults to `error` (errors only).
 
 The SDK never logs plaintext data.
 

package/dist/bin/stash.js

@@ -1125,13 +1125,71 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
   } };
 };
 
-// src/bin/commands/init/types.ts
-var CancelledError = class extends Error {
-  constructor() {
-    super("cancelled");
-    this.name = "CancelledError";
-  }
-};
+// src/bin/commands/init/providers/base.ts
+function createBaseProvider() {
+  return {
+    name: "base",
+    introMessage: "Setting up CipherStash for your project...",
+    connectionOptions: [
+      { value: "drizzle", label: "Drizzle ORM", hint: "recommended" },
+      { value: "prisma", label: "Prisma" },
+      { value: "raw-sql", label: "Raw SQL / pg" }
+    ],
+    getNextSteps(state) {
+      const steps = [
+        "Install @cipherstash/stack: npm install @cipherstash/stack"
+      ];
+      if (state.connectionMethod === "drizzle") {
+        steps.push("Import encryptedType from @cipherstash/stack/drizzle");
+      } else if (state.connectionMethod === "prisma") {
+        steps.push("Set up Prisma with @cipherstash/stack");
+      }
+      steps.push(
+        "Define your encrypted schema",
+        "Read the docs: https://docs.cipherstash.com"
+      );
+      return steps;
+    }
+  };
+}
+
+// src/bin/commands/init/providers/supabase.ts
+function createSupabaseProvider() {
+  return {
+    name: "supabase",
+    introMessage: "Setting up CipherStash for your Supabase project...",
+    connectionOptions: [
+      {
+        value: "supabase-js",
+        label: "Supabase JS Client",
+        hint: "recommended"
+      },
+      { value: "drizzle", label: "Drizzle ORM" },
+      { value: "prisma", label: "Prisma" },
+      { value: "raw-sql", label: "Raw SQL / pg" }
+    ],
+    getNextSteps(state) {
+      const steps = [
+        "Install @cipherstash/stack: npm install @cipherstash/stack"
+      ];
+      if (state.connectionMethod === "supabase-js") {
+        steps.push("Import encryptedSupabase from @cipherstash/stack/supabase");
+      } else if (state.connectionMethod === "drizzle") {
+        steps.push("Import encryptedType from @cipherstash/stack/drizzle");
+      } else if (state.connectionMethod === "prisma") {
+        steps.push("Set up Prisma with @cipherstash/stack");
+      }
+      steps.push(
+        "Define your encrypted schema",
+        "Supabase guides: https://cipherstash.com/docs/supabase/encrypt-user-data",
+        "Multi-tenant encryption: https://docs.cipherstash.com/docs/multi-tenant",
+        "Migrating existing data: https://docs.cipherstash.com/docs/migration",
+        "Need help? #supabase in Discord or support@cipherstash.com"
+      );
+      return steps;
+    }
+  };
+}
 
 // src/bin/commands/init/stubs.ts
 function delay(ms) {
@@ -1174,6 +1232,14 @@ async function installEqlExtension(databaseUrl) {
   await delay(1500);
 }
 
+// src/bin/commands/init/types.ts
+var CancelledError = class extends Error {
+  constructor() {
+    super("cancelled");
+    this.name = "CancelledError";
+  }
+};
+
 // src/bin/commands/init/steps/authenticate.ts
 var authenticateStep = {
   id: "authenticate",
@@ -1195,78 +1261,6 @@ Code:  ${userCode}`,
   }
 };
 
-// src/bin/commands/init/steps/select-workspace.ts
-var selectWorkspaceStep = {
-  id: "select-workspace",
-  name: "Select workspace",
-  async run(state, _provider) {
-    const s = Y2();
-    s.start("Loading workspaces...");
-    const workspaces = await fetchWorkspaces(state.accessToken);
-    s.stop("Workspaces loaded");
-    const options = [
-      ...workspaces.map((ws2) => ({ value: ws2.id, label: ws2.name })),
-      { value: "__create__", label: "Create new workspace" }
-    ];
-    const selected = await ve({
-      message: "Select a workspace",
-      options
-    });
-    if (pD(selected)) throw new CancelledError();
-    if (selected === "__create__") {
-      const name = await he({
-        message: "What should we call your new workspace?",
-        placeholder: "my-project",
-        validate: (val) => {
-          if (!val.trim()) return "Workspace name is required";
-        }
-      });
-      if (pD(name)) throw new CancelledError();
-      const s2 = Y2();
-      s2.start("Creating workspace...");
-      const ws2 = await createWorkspace(state.accessToken, name);
-      s2.stop(`Workspace created: ${ws2.name}`);
-      return { ...state, workspaceId: ws2.id, workspaceName: ws2.name };
-    }
-    const ws = workspaces.find((w2) => w2.id === selected);
-    return { ...state, workspaceId: ws.id, workspaceName: ws.name };
-  }
-};
-
-// src/bin/commands/init/steps/select-region.ts
-var REGIONS = [
-  { value: "ap-southeast-2", label: "Asia Pacific (Sydney)" },
-  { value: "us-east-1", label: "US East (N. Virginia)" },
-  { value: "us-west-2", label: "US West (Oregon)" },
-  { value: "eu-west-1", label: "Europe (Ireland)" }
-];
-var selectRegionStep = {
-  id: "select-region",
-  name: "Select region",
-  async run(state, _provider) {
-    const region = await ve({
-      message: "Where should we create your workspace?",
-      options: REGIONS
-    });
-    if (pD(region)) throw new CancelledError();
-    return { ...state, region };
-  }
-};
-
-// src/bin/commands/init/steps/select-connection.ts
-var selectConnectionStep = {
-  id: "select-connection",
-  name: "Select connection method",
-  async run(state, provider) {
-    const method = await ve({
-      message: "How will you connect to your database?",
-      options: provider.connectionOptions
-    });
-    if (pD(method)) throw new CancelledError();
-    return { ...state, connectionMethod: method };
-  }
-};
-
 // src/bin/commands/init/steps/detect-database-url.ts
 function maskUrl(url) {
   return url.replace(/:\/\/([^:]+):([^@]+)@/, "://***@");
@@ -1296,7 +1290,8 @@ var detectDatabaseUrlStep = {
         placeholder: "postgresql://user:password@host:5432/database",
         validate: (val) => {
           if (!val.trim()) return "Database URL is required";
-          if (!val.startsWith("postgres")) return "Must be a PostgreSQL connection string";
+          if (!val.startsWith("postgres"))
+            return "Must be a PostgreSQL connection string";
         }
       });
       if (pD(url)) throw new CancelledError();
@@ -1358,67 +1353,77 @@ var nextStepsStep = {
   }
 };
 
-// src/bin/commands/init/providers/supabase.ts
-function createSupabaseProvider() {
-  return {
-    name: "supabase",
-    introMessage: "Setting up CipherStash for your Supabase project...",
-    connectionOptions: [
-      { value: "supabase-js", label: "Supabase JS Client", hint: "recommended" },
-      { value: "drizzle", label: "Drizzle ORM" },
-      { value: "prisma", label: "Prisma" },
-      { value: "raw-sql", label: "Raw SQL / pg" }
-    ],
-    getNextSteps(state) {
-      const steps = [
-        "Install @cipherstash/stack: npm install @cipherstash/stack"
-      ];
-      if (state.connectionMethod === "supabase-js") {
-        steps.push("Import encryptedSupabase from @cipherstash/stack/supabase");
-      } else if (state.connectionMethod === "drizzle") {
-        steps.push("Import encryptedType from @cipherstash/stack/drizzle");
-      } else if (state.connectionMethod === "prisma") {
-        steps.push("Set up Prisma with @cipherstash/stack");
-      }
-      steps.push(
-        "Define your encrypted schema",
-        "Supabase guides: https://cipherstash.com/docs/supabase/encrypt-user-data",
-        "Multi-tenant encryption: https://docs.cipherstash.com/docs/multi-tenant",
-        "Migrating existing data: https://docs.cipherstash.com/docs/migration",
-        "Need help? #supabase in Discord or support@cipherstash.com"
-      );
-      return steps;
-    }
-  };
-}
+// src/bin/commands/init/steps/select-connection.ts
+var selectConnectionStep = {
+  id: "select-connection",
+  name: "Select connection method",
+  async run(state, provider) {
+    const method = await ve({
+      message: "How will you connect to your database?",
+      options: provider.connectionOptions
+    });
+    if (pD(method)) throw new CancelledError();
+    return { ...state, connectionMethod: method };
+  }
+};
 
-// src/bin/commands/init/providers/base.ts
-function createBaseProvider() {
-  return {
-    name: "base",
-    introMessage: "Setting up CipherStash for your project...",
-    connectionOptions: [
-      { value: "drizzle", label: "Drizzle ORM", hint: "recommended" },
-      { value: "prisma", label: "Prisma" },
-      { value: "raw-sql", label: "Raw SQL / pg" }
-    ],
-    getNextSteps(state) {
-      const steps = [
-        "Install @cipherstash/stack: npm install @cipherstash/stack"
-      ];
-      if (state.connectionMethod === "drizzle") {
-        steps.push("Import encryptedType from @cipherstash/stack/drizzle");
-      } else if (state.connectionMethod === "prisma") {
-        steps.push("Set up Prisma with @cipherstash/stack");
-      }
-      steps.push(
-        "Define your encrypted schema",
-        "Read the docs: https://docs.cipherstash.com"
-      );
-      return steps;
+// src/bin/commands/init/steps/select-region.ts
+var REGIONS = [
+  { value: "ap-southeast-2", label: "Asia Pacific (Sydney)" },
+  { value: "us-east-1", label: "US East (N. Virginia)" },
+  { value: "us-west-2", label: "US West (Oregon)" },
+  { value: "eu-west-1", label: "Europe (Ireland)" }
+];
+var selectRegionStep = {
+  id: "select-region",
+  name: "Select region",
+  async run(state, _provider) {
+    const region = await ve({
+      message: "Where should we create your workspace?",
+      options: REGIONS
+    });
+    if (pD(region)) throw new CancelledError();
+    return { ...state, region };
+  }
+};
+
+// src/bin/commands/init/steps/select-workspace.ts
+var selectWorkspaceStep = {
+  id: "select-workspace",
+  name: "Select workspace",
+  async run(state, _provider) {
+    const s = Y2();
+    s.start("Loading workspaces...");
+    const workspaces = await fetchWorkspaces(state.accessToken);
+    s.stop("Workspaces loaded");
+    const options = [
+      ...workspaces.map((ws2) => ({ value: ws2.id, label: ws2.name })),
+      { value: "__create__", label: "Create new workspace" }
+    ];
+    const selected = await ve({
+      message: "Select a workspace",
+      options
+    });
+    if (pD(selected)) throw new CancelledError();
+    if (selected === "__create__") {
+      const name = await he({
+        message: "What should we call your new workspace?",
+        placeholder: "my-project",
+        validate: (val) => {
+          if (!val.trim()) return "Workspace name is required";
+        }
+      });
+      if (pD(name)) throw new CancelledError();
+      const s2 = Y2();
+      s2.start("Creating workspace...");
+      const ws2 = await createWorkspace(state.accessToken, name);
+      s2.stop(`Workspace created: ${ws2.name}`);
+      return { ...state, workspaceId: ws2.id, workspaceName: ws2.name };
     }
-  };
-}
+    const ws = workspaces.find((w2) => w2.id === selected);
+    return { ...state, workspaceId: ws.id, workspaceName: ws.name };
+  }
+};
 
 // src/bin/commands/init/index.ts
 var PROVIDER_MAP = {
@@ -1501,15 +1506,6 @@ function isEncryptedPayload(value) {
   return true;
 }
 
-// src/errors/index.ts
-var EncryptionErrorTypes = {
-  ClientInitError: "ClientInitError",
-  EncryptionError: "EncryptionError",
-  DecryptionError: "DecryptionError",
-  LockContextError: "LockContextError",
-  CtsTokenError: "CtsTokenError"
-};
-
 // src/schema/index.ts
 import { z as z2 } from "zod";
 var castAsEnum = z2.enum(["bigint", "boolean", "date", "number", "string", "json", "text"]).default("text");
@@ -1834,6 +1830,15 @@ function buildEncryptConfig(...protectTables) {
   return config3;
 }
 
+// src/errors/index.ts
+var EncryptionErrorTypes = {
+  ClientInitError: "ClientInitError",
+  EncryptionError: "EncryptionError",
+  DecryptionError: "DecryptionError",
+  LockContextError: "LockContextError",
+  CtsTokenError: "CtsTokenError"
+};
+
 // src/utils/config/index.ts
 import fs from "node:fs";
 import path from "node:path";
@@ -1898,26 +1903,34 @@ function loadWorkSpaceId(suppliedCrn) {
 }
 
 // src/utils/logger/index.ts
-import { initLogger, createRequestLogger } from "evlog";
-function samplingFromEnv() {
-  const env = process.env.STASH_LOG_LEVEL;
-  if (!env) return void 0;
-  const levels = ["debug", "info", "warn", "error"];
-  const idx = levels.indexOf(env);
-  if (idx === -1) return void 0;
-  return Object.fromEntries(levels.map((l2, i) => [l2, i >= idx ? 100 : 0]));
+import { createRequestLogger, initLogger } from "evlog";
+var validLevels = ["debug", "info", "error"];
+function levelFromEnv() {
+  const env = process.env.STASH_STACK_LOG;
+  if (env && validLevels.includes(env)) return env;
+  return "error";
+}
+function samplingRatesForLevel(level) {
+  switch (level) {
+    case "debug":
+      return { debug: 100, info: 100, warn: 100, error: 100 };
+    case "info":
+      return { debug: 0, info: 100, warn: 100, error: 100 };
+    case "error":
+    default:
+      return { debug: 0, info: 0, warn: 0, error: 100 };
+  }
 }
 var initialized = false;
-function initStackLogger(config3) {
+function initStackLogger() {
   if (initialized) return;
   initialized = true;
-  const rates = samplingFromEnv();
+  const level = levelFromEnv();
+  const rates = samplingRatesForLevel(level);
   initLogger({
     env: { service: "@cipherstash/stack" },
-    enabled: config3?.enabled ?? !!rates,
-    pretty: config3?.pretty,
-    ...rates && { sampling: { rates } },
-    ...config3?.drain && { drain: config3.drain }
+    enabled: true,
+    sampling: { rates }
   });
 }
 initStackLogger();
@@ -1955,6 +1968,7 @@ var logger = {
 // src/encryption/index.ts
 import { withResult as withResult11 } from "@byteslice/result";
 import { newClient } from "@cipherstash/protect-ffi";
+import { validate as uuidValidate } from "uuid";
 
 // src/encryption/helpers/type-guards.ts
 function isScalarQueryTermArray(value) {
@@ -4245,23 +4259,14 @@ var EncryptionClient = class {
     };
   }
 };
-
-// src/index.ts
-function isValidUuid(uuid) {
-  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-  return uuidRegex.test(uuid);
-}
 var Encryption = async (config3) => {
-  if (config3.logging) {
-    initStackLogger(config3.logging);
-  }
   const { schemas, config: clientConfig } = config3;
   if (!schemas.length) {
     throw new Error(
       "[encryption]: At least one encryptedTable must be provided to initialize the encryption client"
     );
   }
-  if (clientConfig?.keyset && "id" in clientConfig.keyset && !isValidUuid(clientConfig.keyset.id)) {
+  if (clientConfig?.keyset && "id" in clientConfig.keyset && !uuidValidate(clientConfig.keyset.id)) {
     throw new Error(
       "[encryption]: Invalid UUID provided for keyset id. Must be a valid UUID."
     );
@@ -4287,7 +4292,22 @@ var Secrets = class {
     value: encryptedColumn("value")
   });
   constructor(config3) {
-    this.config = config3;
+    const workspaceCRN = config3.workspaceCRN ?? process.env.CS_WORKSPACE_CRN;
+    const clientId = config3.clientId ?? process.env.CS_CLIENT_ID;
+    const clientKey = config3.clientKey ?? process.env.CS_CLIENT_KEY;
+    const accessKey = config3.accessKey ?? process.env.CS_CLIENT_ACCESS_KEY;
+    if (!workspaceCRN || !clientId || !clientKey || !accessKey) {
+      throw new Error(
+        "Missing required configuration or environment variables."
+      );
+    }
+    this.config = {
+      environment: config3.environment,
+      workspaceCRN,
+      clientId,
+      clientKey,
+      accessKey
+    };
   }
   initPromise = null;
   /**
@@ -4300,24 +4320,24 @@ var Secrets = class {
     return this.initPromise;
   }
   async _doInit() {
+    logger.debug("Initializing the Secrets client.");
     this.encryptionClient = await Encryption({
       schemas: [this.secretsSchema],
       config: {
         workspaceCrn: this.config.workspaceCRN,
         clientId: this.config.clientId,
         clientKey: this.config.clientKey,
-        accessKey: this.config.apiKey,
-        keyset: {
-          name: this.config.environment
-        }
+        accessKey: this.config.accessKey,
+        keyset: { name: this.config.environment }
       }
     });
+    logger.debug("Successfully initialized the Secrets client.");
   }
   /**
    * Get the authorization header for API requests
    */
   getAuthHeader() {
-    return `Bearer ${this.config.apiKey}`;
+    return `Bearer ${this.config.accessKey}`;
   }
   /**
    * Make an API request with error handling.
@@ -4332,6 +4352,7 @@ var Secrets = class {
         const searchParams = new URLSearchParams(options.params);
         url = `${url}?${searchParams.toString()}`;
       }
+      logger.debug(`Secrets API request: ${method} ${path2}`);
       const headers = {
         "Content-Type": "application/json",
         Authorization: this.getAuthHeader()
@@ -4350,6 +4371,7 @@ var Secrets = class {
         } catch {
           errorMessage = errorText || errorMessage;
         }
+        logger.error(`Secrets API error on ${method} ${path2}: ${errorMessage}`);
         return {
           failure: {
             type: "ApiError",
@@ -4357,13 +4379,16 @@ var Secrets = class {
           }
         };
       }
+      logger.debug(`Secrets API request successful: ${method} ${path2}`);
       const data = await response.json();
       return { data };
     } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown network error occurred";
+      logger.error(`Secrets network error on ${method} ${path2}: ${message}`);
       return {
         failure: {
           type: "NetworkError",
-          message: error instanceof Error ? error.message : "Unknown network error occurred"
+          message
         }
       };
     }
@@ -4379,6 +4404,7 @@ var Secrets = class {
    * @returns A Result containing the API response or an error
    */
   async set(name, value) {
+    logger.debug("Setting secret");
     await this.ensureInitialized();
     if (!this.encryptionClient) {
       return {
@@ -4393,6 +4419,7 @@ var Secrets = class {
       table: this.secretsSchema
     });
     if (encryptResult.failure) {
+      logger.error("Failed to encrypt secret");
       return {
         failure: {
           type: "EncryptionError",
@@ -4420,6 +4447,7 @@ var Secrets = class {
    * @returns A Result containing the decrypted value or an error
    */
   async get(name) {
+    logger.debug("Getting secret");
     await this.ensureInitialized();
     if (!this.encryptionClient) {
       return {
@@ -4444,6 +4472,7 @@ var Secrets = class {
       apiResult.data.encryptedValue.data
     );
     if (decryptResult.failure) {
+      logger.error("Failed to decrypt secret");
       return {
         failure: {
           type: "DecryptionError",
@@ -4452,6 +4481,7 @@ var Secrets = class {
       };
     }
     if (typeof decryptResult.data !== "string") {
+      logger.error("Decrypted secret value is not a string");
       return {
         failure: {
           type: "DecryptionError",
@@ -4476,6 +4506,7 @@ var Secrets = class {
    * @returns A Result containing an object mapping secret names to their decrypted values
    */
   async getMany(names) {
+    logger.debug(`Getting ${names.length} secrets.`);
     await this.ensureInitialized();
     if (!this.encryptionClient) {
       return {
@@ -4522,6 +4553,9 @@ var Secrets = class {
     }));
     const decryptResult = await this.encryptionClient.bulkDecryptModels(dataToDecrypt);
     if (decryptResult.failure) {
+      logger.error(
+        `Failed to decrypt secrets: ${decryptResult.failure.message}`
+      );
       return {
         failure: {
           type: "DecryptionError",
@@ -4547,6 +4581,7 @@ var Secrets = class {
    * @returns A Result containing the list of secrets or an error
    */
   async list() {
+    logger.debug("Listing secrets.");
     const workspaceId = extractWorkspaceIdFromCrn(this.config.workspaceCRN);
     const apiResult = await this.apiRequest(
       "GET",
@@ -4572,6 +4607,7 @@ var Secrets = class {
    * @returns A Result containing the API response or an error
    */
   async delete(name) {
+    logger.debug("Deleting secret");
     const workspaceId = extractWorkspaceIdFromCrn(this.config.workspaceCRN);
     return await this.apiRequest("POST", "/delete", {
       body: {