feat(stack): export operation classes returned by public methods

Export the operation classes returned by the encryption and DynamoDB clients (plus EncryptedQuery and EncryptedFromSchema) so they are part of the public API and appear in the generated TypeDoc reference. This makes the TSDoc {@link} cross-references and method return types resolve to real pages instead of failing to resolve or pointing at undocumented symbols.

- encryption: Encrypt/EncryptQuery/Decrypt/Bulk*/*Model* operation classes
- dynamodb: model operation classes
- types: EncryptedQuery, EncryptedFromSchema
- EncryptQueryOperation / BatchEncryptQueryOperation are no longer @internal, for consistency with the other operations (they are returned from encryptQuery)
- add type-only imports for {@link} resolution; fix the init reference and a buildEncryptConfig @param name

Author: coderdan

.changeset/export-operation-result-types.md

@@ -0,0 +1,15 @@
+---
+"@cipherstash/stack": minor
+---
+
+Export the operation classes returned by the encryption and DynamoDB clients as public API.
+
+The classes returned from public methods are now exported and documented in the API reference, so their types can be named and their TSDoc links resolve.
+
+- From `@cipherstash/stack/encryption`: `EncryptOperation`, `EncryptQueryOperation`, `BatchEncryptQueryOperation`, `DecryptOperation`, `EncryptModelOperation`, `DecryptModelOperation`, `BulkEncryptOperation`, `BulkDecryptOperation`, `BulkEncryptModelsOperation`, `BulkDecryptModelsOperation`. `EncryptQueryOperation` and `BatchEncryptQueryOperation` were previously marked `@internal`; since they are returned from `EncryptionClient.encryptQuery`, they are now public for consistency with the other operations.
+- From `@cipherstash/stack/dynamodb`: `EncryptModelOperation`, `DecryptModelOperation`, `BulkEncryptModelsOperation`, `BulkDecryptModelsOperation`.
+- From `@cipherstash/stack/types`: `EncryptedQuery` and `EncryptedFromSchema`.
+
+The `*WithLockContext` variants returned by `.withLockContext()` remain internal — they share the same awaitable shape and are not intended to be named directly.
+
+No runtime behaviour changes; this only widens the exported surface and corrects TSDoc cross-references that previously failed to resolve.

packages/stack/src/dynamodb/index.ts

@@ -97,3 +97,12 @@ export type {
   EncryptedDynamoDBError,
   EncryptedDynamoDBInstance,
 } from './types'
+
+// Re-export the operation classes returned by the DynamoDB instance methods so
+// they are part of the public API and appear in the generated reference.
+export {
+  EncryptModelOperation,
+  DecryptModelOperation,
+  BulkEncryptModelsOperation,
+  BulkDecryptModelsOperation,
+}

packages/stack/src/encryption/index.ts

@@ -1,10 +1,17 @@
 import { type EncryptionError, EncryptionErrorTypes } from '@/errors'
+// `LockContext` is imported type-only so the TSDoc {@link} references in the
+// comments below resolve; it is erased at compile time.
+import type { LockContext } from '@/identity'
 import {
   type EncryptConfig,
   type EncryptedTable,
   type EncryptedTableColumn,
   buildEncryptConfig,
   encryptConfigSchema,
+  // Imported type-only for the TSDoc {@link} references in the comments below.
+  type encryptedColumn,
+  type encryptedField,
+  type encryptedTable,
 } from '@/schema'
 import type {
   BulkDecryptPayload,
@@ -35,6 +42,22 @@ import { EncryptOperation } from './operations/encrypt'
 import { EncryptModelOperation } from './operations/encrypt-model'
 import { EncryptQueryOperation } from './operations/encrypt-query'
 
+// Re-export the operation classes returned by EncryptionClient methods so they
+// are part of the public API and appear in the generated reference, allowing
+// TSDoc {@link} references and method return types to resolve to real pages.
+export {
+  EncryptOperation,
+  EncryptQueryOperation,
+  BatchEncryptQueryOperation,
+  DecryptOperation,
+  EncryptModelOperation,
+  DecryptModelOperation,
+  BulkEncryptOperation,
+  BulkDecryptOperation,
+  BulkEncryptModelsOperation,
+  BulkDecryptModelsOperation,
+}
+
 export const noClientError = () =>
   new Error(
     'The Encryption client has not been initialized. Please call init() before using the client.',
@@ -610,7 +633,7 @@ export class EncryptionClient {
  *   {@link EncryptionClient.encrypt}, {@link EncryptionClient.decrypt}, and related operations.
  *
  * @throws Throws if `schemas` is empty, or if a keyset `id` is supplied but is not a valid UUID.
- *   Also throws if {@link EncryptionClient.init} fails (e.g. invalid credentials or config).
+ *   Also throws if the client fails to initialize (e.g. invalid credentials or config).
  *
  * @example
  * ```typescript

packages/stack/src/encryption/operations/batch-encrypt-query.ts

@@ -91,9 +91,6 @@ function assembleResults(
   return results
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input instead.
- */
 export class BatchEncryptQueryOperation extends EncryptionOperation<
   EncryptedQueryResult[]
 > {
@@ -168,9 +165,6 @@ export class BatchEncryptQueryOperation extends EncryptionOperation<
   }
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with array input and `.withLockContext()` instead.
- */
 export class BatchEncryptQueryOperationWithLockContext extends EncryptionOperation<
   EncryptedQueryResult[]
 > {

packages/stack/src/encryption/operations/encrypt-query.ts

@@ -17,9 +17,6 @@ import {
 import { noClientError } from '../index'
 import { EncryptionOperation } from './base-operation'
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} instead.
- */
 export class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryResult> {
   constructor(
     private client: Client,
@@ -114,9 +111,6 @@ export class EncryptQueryOperation extends EncryptionOperation<EncryptedQueryRes
   }
 }
 
-/**
- * @internal Use {@link EncryptionClient.encryptQuery} with `.withLockContext()` instead.
- */
 export class EncryptQueryOperationWithLockContext extends EncryptionOperation<EncryptedQueryResult> {
   constructor(
     private client: Client,

packages/stack/src/schema/index.ts

@@ -658,7 +658,7 @@ export function encryptedField(valueName: string) {
 /**
  * Build an encrypt config from a list of encrypted tables.
  *
- * @param ...tables - The list of encrypted tables to build the config from.
+ * @param protectTables - The list of encrypted tables to build the config from.
  * @returns An encrypt config object.
  *
  * @example

packages/stack/src/types-public.ts

@@ -11,6 +11,7 @@ export type {
   Client,
   EncryptedValue,
   Encrypted,
+  EncryptedQuery,
 } from '@/types'
 
 // Client configuration
@@ -35,6 +36,7 @@ export type {
   OtherFields,
   DecryptedFields,
   Decrypted,
+  EncryptedFromSchema,
 } from '@/types'
 
 // Bulk operations

packages/stack/src/types.ts

@@ -3,6 +3,9 @@ import type {
   EncryptedField,
   EncryptedTable,
   EncryptedTableColumn,
+  // Imported type-only for the TSDoc {@link} references in the comments below.
+  encryptedColumn,
+  encryptedField,
 } from '@/schema'
 import type {
   Encrypted as CipherStashEncrypted,