@pattern-stack/codegen 0.10.1 → 0.11.0

package/examples/auth-integrations/README.md

@@ -1,12 +1,12 @@
 # auth-integrations starter
 
-Canonical OAuth2 integration storage for apps using the
+Canonical OAuth2 connection storage for apps using the
 `@pattern-stack/codegen` auth subsystem (ADR-031 / `runtime/subsystems/auth/`).
 
 The auth subsystem ships the abstract OAuth2 plumbing — `OAuth2RefreshStrategy`,
 `AuthController`, `withAuthRetry`, encryption, error types, and a set of narrow
-hexagonal ports for integration storage. It deliberately doesn't ship the
-concrete `integrations` table or the adapters that satisfy those ports, because
+hexagonal ports for connection storage. It deliberately doesn't ship the
+concrete `connections` table or the adapters that satisfy those ports, because
 every consumer would need to fork them. **This starter is what plugs that gap.**
 
 ## What ships here
@@ -15,26 +15,26 @@ every consumer would need to fork them. **This starter is what plugs that gap.**
 examples/auth-integrations/
   definitions/
     entities/
-      integration.yaml                      # canonical entity (run cdp entity new)
+      connection.yaml                      # canonical entity (run cdp entity new)
 
-  runtime/integrations/                     # vendored next to the codegen-emitted
-                                            #   integration entity module — i.e.
-                                            #   <backend_src>/modules/integrations/
+  runtime/connections/                     # vendored next to the codegen-emitted
+                                            #   connection entity module — i.e.
+                                            #   <backend_src>/modules/connections/
                                             #   (override via paths.modules_dir).
     adapters/
-      integration-reader.adapter.ts         # IIntegrationReader impl
-      integration-token-writer.adapter.ts   # IIntegrationTokenWriter impl
-      integration-grant-sink.adapter.ts     # IIntegrationGrantSink impl
+      connection-reader.adapter.ts         # IConnectionReader impl
+      connection-token-writer.adapter.ts   # IConnectionTokenWriter impl
+      connection-grant-sink.adapter.ts     # IConnectionGrantSink impl
     facade/
-      integrations.service.ts               # consumer-facing facade
+      connections.service.ts               # consumer-facing facade
     oauth/
       use-cases/
         create-or-update-from-oauth-grant.use-case.ts
-        mark-integration-requires-reauth.use-case.ts
-        disconnect-integration.use-case.ts
-        list-user-integrations.use-case.ts
-    integrations-auth.module.ts             # @Global() — binds the three
-                                            #   AUTH_INTEGRATION_* tokens.
+        mark-connection-requires-reauth.use-case.ts
+        disconnect-connection.use-case.ts
+        list-user-connections.use-case.ts
+    connections-auth.module.ts             # @Global() — binds the three
+                                            #   AUTH_CONNECTION_* tokens.
 ```
 
 ## How to install
@@ -42,22 +42,22 @@ examples/auth-integrations/
 ```bash
 cdp subsystem install auth          # one-time: vendor the auth subsystem
 cdp subsystem install auth-integrations
-cdp entity new integration          # emits the entity module next to the vendor
+cdp entity new connection          # emits the entity module next to the vendor
 ```
 
 The `auth-integrations` install:
-- copies `definitions/entities/integration.yaml` into your configured
+- copies `definitions/entities/connection.yaml` into your configured
   `paths.entities` (or legacy `paths.entities_dir`) directory.
-- vendors `runtime/integrations/**` under
-  `<backend_src>/modules/integrations/` (override via `paths.modules_dir`),
+- vendors `runtime/connections/**` under
+  `<backend_src>/modules/connections/` (override via `paths.modules_dir`),
   rewriting bare `@pattern-stack/codegen/runtime/subsystems/auth` imports to
   relative paths that resolve against the vendored auth subsystem at
   `<paths.subsystems>/auth`.
 - appends a TODO to `<backend_src>/app.module.ts` reminding you to register
-  `IntegrationsAuthModule` AFTER `AuthModule.forRoot(...)`.
+  `ConnectionsAuthModule` AFTER `AuthModule.forRoot(...)`.
 
-`IntegrationsAuthModule` is `@Global()` because `AuthController` (inside
-`AuthModule`'s injector) resolves the `AUTH_INTEGRATION_*` providers exposed
+`ConnectionsAuthModule` is `@Global()` because `AuthController` (inside
+`AuthModule`'s injector) resolves the `AUTH_CONNECTION_*` providers exposed
 by it.
 
 ## Two interfaces, two purposes
@@ -66,15 +66,15 @@ The auth subsystem requires three narrow ports:
 
 | Token                            | Port                       | Used by                        |
 | -------------------------------- | -------------------------- | ------------------------------ |
-| `AUTH_INTEGRATION_READER`        | `IIntegrationReader`       | `OAuth2RefreshStrategy.resolve` |
-| `AUTH_INTEGRATION_TOKEN_WRITER`  | `IIntegrationTokenWriter`  | `OAuth2RefreshStrategy.resolve` |
-| `AUTH_INTEGRATION_GRANT_SINK`    | `IIntegrationGrantSink`    | `AuthController.callback`       |
+| `AUTH_CONNECTION_READER`        | `IConnectionReader`       | `OAuth2RefreshStrategy.resolve` |
+| `AUTH_CONNECTION_TOKEN_WRITER`  | `IConnectionTokenWriter`  | `OAuth2RefreshStrategy.resolve` |
+| `AUTH_CONNECTION_GRANT_SINK`    | `IConnectionGrantSink`    | `AuthController.callback`       |
 
 These stay narrow on purpose — a non-codegen consumer with a hand-rolled
-integrations table can satisfy them without pulling in the rest of this
+connections table can satisfy them without pulling in the rest of this
 starter.
 
-The starter's `IntegrationsService` is **a separate, richer interface** that
+The starter's `ConnectionsService` is **a separate, richer interface** that
 your app code (controllers, handlers, frontend-facing routes) talks to
 directly. It composes the use cases, applies encryption, and exposes
 consumer-shaped methods like `findByUserAndProvider`, `listByUser`,
@@ -104,14 +104,14 @@ supports any provider slug your app cares about.
 
 After install:
 
-- [ ] `IntegrationsService.findByUserAndProvider(userId, 'hubspot-crm')`
+- [ ] `ConnectionsService.findByUserAndProvider(userId, 'hubspot-crm')`
       returns `null` for missing rows, decrypted-creds for present rows.
 - [ ] `createOrUpdateFromOAuthGrant({ userId, provider, accessToken, ... })`
       upserts on `(user_id, provider)`. Re-running with a different access
       token replaces the prior token; omitting `refreshToken` keeps the
       existing ciphertext.
-- [ ] `markRequiresReauth(integrationId)` flips status to `requires_reauth`.
-- [ ] `disconnect(integrationId)` flips status to `revoked` and clears the
+- [ ] `markRequiresReauth(connectionId)` flips status to `requires_reauth`.
+- [ ] `disconnect(connectionId)` flips status to `revoked` and clears the
       stored ciphertexts.
 - [ ] `OAuth2RefreshStrategy.resolve()` end-to-end refresh works against a
       provider-strategy you've registered (out of scope — provider strategies
@@ -121,5 +121,5 @@ After install:
 
 - ADR-031 — auth subsystem (Accepted)
 - #285 — this starter (tracking issue)
-- #286 — `AuthController` + integration-store ports (merged in PR #289)
+- #286 — `AuthController` + connection-store ports (merged in PR #289)
 - #287 — `cdp subsystem install auth-integrations` template (follow-up)

package/examples/auth-integrations/definitions/entities/{integration.yaml → connection.yaml}

@@ -1,7 +1,7 @@
-# auth-integrations: Integration
-# Canonical OAuth2 integration row — one per (user_id, provider) pair.
-# Vendored alongside the auth subsystem to satisfy IIntegrationReader /
-# IIntegrationTokenWriter / IIntegrationGrantSink ports out of the box.
+# auth-integrations: Connection
+# Canonical OAuth2 connection row — one per (user_id, provider) pair.
+# Vendored alongside the auth subsystem to satisfy IConnectionReader /
+# IConnectionTokenWriter / IConnectionGrantSink ports out of the box.
 #
 # `provider` stays a string (not enum) intentionally so consumers can add
 # provider keys ('hubspot-crm', 'salesforce-crm', 'google', …) without
@@ -9,9 +9,9 @@
 # STRATEGY_REGISTRY.
 
 entity:
-  name: integration
-  plural: integrations
-  table: integrations
+  name: connection
+  plural: connections
+  table: connections
   pattern: Base
   folder_structure: nested
 
@@ -35,7 +35,7 @@ fields:
     nullable: true
     max_length: 255
 
-  # Ciphertexts — encryption is applied inside the IntegrationsService
+  # Ciphertexts — encryption is applied inside the ConnectionsService
   # facade + adapter layer (via IEncryptionKey). The DB row only ever
   # holds the encrypted form; decryption happens on read in the reader
   # adapter.
@@ -88,11 +88,11 @@ queries:
   - by: [user_id, provider]
     unique: true
 
-  # Settings page: list a user's connected integrations, newest first.
+  # Settings page: list a user's connected connections, newest first.
   - by: [user_id]
     order: created_at desc
 
-  # Operational query: find broken integrations needing reauth across
+  # Operational query: find broken connections needing reauth across
   # all users (admin / monitoring).
   - by: [provider, status]
     order: updated_at desc

package/examples/auth-integrations/runtime/{integrations/adapters/integration-grant-sink.adapter.ts → connections/adapters/connection-grant-sink.adapter.ts}

@@ -1,29 +1,29 @@
 import { Injectable } from '@nestjs/common';
 import type {
-  IIntegrationGrantSink,
-  IntegrationGrantInput,
+  IConnectionGrantSink,
+  ConnectionGrantInput,
 } from '@pattern-stack/codegen/runtime/subsystems/auth';
 import { CreateOrUpdateFromOAuthGrantUseCase } from '../oauth/use-cases/create-or-update-from-oauth-grant.use-case';
 
 /**
- * `IIntegrationGrantSink` adapter — pass-through to
+ * `IConnectionGrantSink` adapter — pass-through to
  * `CreateOrUpdateFromOAuthGrantUseCase`. The auth subsystem's
  * `AuthController.callback` invokes this after
  * `IProviderStrategy.exchangeCodeForTokens`.
  *
  * This adapter injects the use case directly (not the
- * `IntegrationsService` facade) for symmetry with the reader and
+ * `ConnectionsService` facade) for symmetry with the reader and
  * token-writer adapters, which also bypass the facade and talk to
  * the codegen-emitted layer directly. The port and the use case share
- * the exact same `IntegrationGrantInput` shape, so no field mapping is
+ * the exact same `ConnectionGrantInput` shape, so no field mapping is
  * needed — encryption, upsert resolution, and status handling all live
  * inside the use case.
  */
 @Injectable()
-export class IntegrationGrantSinkAdapter implements IIntegrationGrantSink {
+export class ConnectionGrantSinkAdapter implements IConnectionGrantSink {
   constructor(private readonly useCase: CreateOrUpdateFromOAuthGrantUseCase) {}
 
-  async createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void> {
+  async createOrUpdateFromOAuthGrant(input: ConnectionGrantInput): Promise<void> {
     await this.useCase.execute(input);
   }
 }

package/examples/auth-integrations/runtime/{integrations/adapters/integration-reader.adapter.ts → connections/adapters/connection-reader.adapter.ts}

@@ -1,21 +1,21 @@
 import { Inject, Injectable } from '@nestjs/common';
 import {
   ENCRYPTION_KEY,
-  type DecryptedIntegration,
+  type DecryptedConnection,
   type IEncryptionKey,
-  type IIntegrationReader,
+  type IConnectionReader,
 } from '@pattern-stack/codegen/runtime/subsystems/auth';
-import { IntegrationService } from '../integration.service';
+import { ConnectionService } from '../connection.service';
 
 /**
- * `IIntegrationReader` adapter — fetches the integration row by id and
+ * `IConnectionReader` adapter — fetches the connection row by id and
  * decrypts its ciphertexts to satisfy the auth subsystem's read port.
  *
  * Stays narrow on purpose: this adapter exists purely to feed
  * `OAuth2RefreshStrategy.resolve()`. Anything wider belongs in
- * `IntegrationsService` (the consumer-facing facade).
+ * `ConnectionsService` (the consumer-facing facade).
  *
- * Note: this duplicates the decryption logic in `IntegrationsService`
+ * Note: this duplicates the decryption logic in `ConnectionsService`
  * by design — the adapter must not depend on the facade because the
  * facade depends on the use cases which depend on the adapter (well,
  * not directly, but via the same module). Keeping the read path
@@ -23,14 +23,14 @@ import { IntegrationService } from '../integration.service';
  * subsystem's "narrow port" contract.
  */
 @Injectable()
-export class IntegrationReaderAdapter implements IIntegrationReader {
+export class ConnectionReaderAdapter implements IConnectionReader {
   constructor(
-    private readonly integrations: IntegrationService,
+    private readonly connections: ConnectionService,
     @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
   ) {}
 
-  async findByIdDecrypted(integrationId: string): Promise<DecryptedIntegration | null> {
-    const row = await this.integrations.findById(integrationId);
+  async findByIdDecrypted(connectionId: string): Promise<DecryptedConnection | null> {
+    const row = await this.connections.findById(connectionId);
     if (!row) return null;
 
     const accessToken = row.accessTokenEncrypted

package/examples/auth-integrations/runtime/{integrations/adapters/integration-token-writer.adapter.ts → connections/adapters/connection-token-writer.adapter.ts}

@@ -2,33 +2,33 @@ import { Inject, Injectable } from '@nestjs/common';
 import {
   ENCRYPTION_KEY,
   type IEncryptionKey,
-  type IIntegrationTokenWriter,
-  type IntegrationTokenUpdate,
+  type IConnectionTokenWriter,
+  type ConnectionTokenUpdate,
 } from '@pattern-stack/codegen/runtime/subsystems/auth';
-import { IntegrationService } from '../integration.service';
+import { ConnectionService } from '../connection.service';
 
 /**
- * `IIntegrationTokenWriter` adapter — encrypts the new access token
+ * `IConnectionTokenWriter` adapter — encrypts the new access token
  * (and rotated refresh token, if present) and persists them onto the
- * integration row.
+ * connection row.
  *
- * `IntegrationTokenUpdate.refreshToken` semantics:
+ * `ConnectionTokenUpdate.refreshToken` semantics:
  *   - `undefined` → provider didn't rotate, leave existing ciphertext
  *   - `string`    → provider rotated, re-encrypt + persist
  *
  * On a successful refresh we also flip status back to 'active' — if
  * the row was previously `requires_reauth` and the user re-connected,
- * a successful refresh is the signal that the integration is healthy
+ * a successful refresh is the signal that the connection is healthy
  * again.
  */
 @Injectable()
-export class IntegrationTokenWriterAdapter implements IIntegrationTokenWriter {
+export class ConnectionTokenWriterAdapter implements IConnectionTokenWriter {
   constructor(
-    private readonly integrations: IntegrationService,
+    private readonly connections: ConnectionService,
     @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
   ) {}
 
-  async persistRefresh(update: IntegrationTokenUpdate): Promise<void> {
+  async persistRefresh(update: ConnectionTokenUpdate): Promise<void> {
     const accessTokenEncrypted = await this.encryption.encrypt(update.accessToken);
     const patch: Record<string, unknown> = {
       accessTokenEncrypted,
@@ -38,6 +38,6 @@ export class IntegrationTokenWriterAdapter implements IIntegrationTokenWriter {
     if (update.refreshToken !== undefined) {
       patch.refreshTokenEncrypted = await this.encryption.encrypt(update.refreshToken);
     }
-    await this.integrations.update(update.integrationId, patch);
+    await this.connections.update(update.connectionId, patch);
   }
 }

package/examples/auth-integrations/runtime/connections/connections-auth.module.ts

@@ -0,0 +1,81 @@
+import { Global, Module } from '@nestjs/common';
+import {
+  AUTH_CONNECTION_GRANT_SINK,
+  AUTH_CONNECTION_READER,
+  AUTH_CONNECTION_TOKEN_WRITER,
+} from '@pattern-stack/codegen/runtime/subsystems/auth';
+import { ConnectionsModule } from './connections.module';
+import { ConnectionGrantSinkAdapter } from './adapters/connection-grant-sink.adapter';
+import { ConnectionReaderAdapter } from './adapters/connection-reader.adapter';
+import { ConnectionTokenWriterAdapter } from './adapters/connection-token-writer.adapter';
+import { ConnectionsService } from './facade/connections.service';
+import { CreateOrUpdateFromOAuthGrantUseCase } from './oauth/use-cases/create-or-update-from-oauth-grant.use-case';
+import { DisconnectConnectionUseCase } from './oauth/use-cases/disconnect-connection.use-case';
+import { ListUserConnectionsUseCase } from './oauth/use-cases/list-user-connections.use-case';
+import { MarkConnectionRequiresReauthUseCase } from './oauth/use-cases/mark-connection-requires-reauth.use-case';
+
+/**
+ * `ConnectionsAuthModule` — wires the consumer-side adapters that
+ * satisfy the auth subsystem's three connection-store ports plus the
+ * `ConnectionsService` facade and its use cases.
+ *
+ * Imports `ConnectionsModule` (the codegen-emitted entity module) to
+ * pull in `ConnectionService` + its repository.
+ *
+ * Depends on a registered `ENCRYPTION_KEY` provider — that comes from
+ * `AuthModule.forRoot({ encryptionKey: ... })`. Make sure
+ * `AuthModule.forRoot(...)` is imported in your app's root module BEFORE
+ * `ConnectionsAuthModule` (or globally — `AuthModule` is `global: true`
+ * by convention).
+ *
+ * Token bindings (per #285 / #286):
+ *   - AUTH_CONNECTION_READER       → ConnectionReaderAdapter
+ *   - AUTH_CONNECTION_TOKEN_WRITER → ConnectionTokenWriterAdapter
+ *   - AUTH_CONNECTION_GRANT_SINK   → ConnectionGrantSinkAdapter
+ *
+ * `@Global()` is required: `AuthController` lives inside `AuthModule`'s
+ * own injector and resolves the `AUTH_CONNECTION_*` providers exposed
+ * here. Without `@Global()`, the controller's injector cannot see these
+ * tokens and Nest fails to boot. Same pattern as the `auth-bindings`
+ * module shipped in #93.
+ */
+@Global()
+@Module({
+  imports: [ConnectionsModule],
+  providers: [
+    // Use cases (consumed by the facade)
+    CreateOrUpdateFromOAuthGrantUseCase,
+    MarkConnectionRequiresReauthUseCase,
+    DisconnectConnectionUseCase,
+    ListUserConnectionsUseCase,
+
+    // Facade (consumer-facing API; controllers/handlers inject this)
+    ConnectionsService,
+
+    // Subsystem port adapters (concrete classes — also exposed under
+    // their token aliases for `@Inject(...)` consumers in the auth
+    // subsystem).
+    ConnectionReaderAdapter,
+    ConnectionTokenWriterAdapter,
+    ConnectionGrantSinkAdapter,
+    {
+      provide: AUTH_CONNECTION_READER,
+      useExisting: ConnectionReaderAdapter,
+    },
+    {
+      provide: AUTH_CONNECTION_TOKEN_WRITER,
+      useExisting: ConnectionTokenWriterAdapter,
+    },
+    {
+      provide: AUTH_CONNECTION_GRANT_SINK,
+      useExisting: ConnectionGrantSinkAdapter,
+    },
+  ],
+  exports: [
+    ConnectionsService,
+    AUTH_CONNECTION_READER,
+    AUTH_CONNECTION_TOKEN_WRITER,
+    AUTH_CONNECTION_GRANT_SINK,
+  ],
+})
+export class ConnectionsAuthModule {}

package/examples/auth-integrations/runtime/{integrations/facade/integrations.service.ts → connections/facade/connections.service.ts}

@@ -2,22 +2,22 @@ import { Inject, Injectable } from '@nestjs/common';
 import {
   ENCRYPTION_KEY,
   type IEncryptionKey,
-  type IntegrationGrantInput,
+  type ConnectionGrantInput,
 } from '@pattern-stack/codegen/runtime/subsystems/auth';
-import { IntegrationService } from '../integration.service';
-import type { Integration } from '../integration.entity';
+import { ConnectionService } from '../connection.service';
+import type { Connection } from '../connection.entity';
 import { CreateOrUpdateFromOAuthGrantUseCase } from '../oauth/use-cases/create-or-update-from-oauth-grant.use-case';
-import { DisconnectIntegrationUseCase } from '../oauth/use-cases/disconnect-integration.use-case';
-import { ListUserIntegrationsUseCase } from '../oauth/use-cases/list-user-integrations.use-case';
-import { MarkIntegrationRequiresReauthUseCase } from '../oauth/use-cases/mark-integration-requires-reauth.use-case';
+import { DisconnectConnectionUseCase } from '../oauth/use-cases/disconnect-connection.use-case';
+import { ListUserConnectionsUseCase } from '../oauth/use-cases/list-user-connections.use-case';
+import { MarkConnectionRequiresReauthUseCase } from '../oauth/use-cases/mark-connection-requires-reauth.use-case';
 
 /**
- * Decrypted integration shape — used by consumer code that needs to
+ * Decrypted connection shape — used by consumer code that needs to
  * make outbound API calls (frontend never sees this; it's server-side
- * only). Mirrors the auth subsystem's `DecryptedIntegration` but is
+ * only). Mirrors the auth subsystem's `DecryptedConnection` but is
  * the consumer-facing return type for `findByUserAndProvider`.
  */
-export interface DecryptedIntegrationRow {
+export interface DecryptedConnectionRow {
   id: string;
   userId: string;
   provider: string;
@@ -34,11 +34,11 @@ export interface DecryptedIntegrationRow {
 }
 
 /**
- * IntegrationsService — consumer-facing facade over the codegen-emitted
- * `IntegrationService` plus the auth subsystem's `IEncryptionKey`.
+ * ConnectionsService — consumer-facing facade over the codegen-emitted
+ * `ConnectionService` plus the auth subsystem's `IEncryptionKey`.
  *
- * Wider than the auth subsystem ports (`IIntegrationReader`,
- * `IIntegrationTokenWriter`, `IIntegrationGrantSink`) on purpose: the
+ * Wider than the auth subsystem ports (`IConnectionReader`,
+ * `IConnectionTokenWriter`, `IConnectionGrantSink`) on purpose: the
  * narrow ports are the subsystem's hexagonal seam (so non-codegen
  * consumers can implement them); the facade is what app code talks to
  * directly (controllers, handlers, frontend-facing use cases).
@@ -52,18 +52,18 @@ export interface DecryptedIntegrationRow {
  * intentionally strips them to a safe metadata shape.
  */
 @Injectable()
-export class IntegrationsService {
+export class ConnectionsService {
   constructor(
-    private readonly integrations: IntegrationService,
+    private readonly connections: ConnectionService,
     @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
     private readonly createOrUpdateUseCase: CreateOrUpdateFromOAuthGrantUseCase,
-    private readonly markReauthUseCase: MarkIntegrationRequiresReauthUseCase,
-    private readonly disconnectUseCase: DisconnectIntegrationUseCase,
-    private readonly listUseCase: ListUserIntegrationsUseCase,
+    private readonly markReauthUseCase: MarkConnectionRequiresReauthUseCase,
+    private readonly disconnectUseCase: DisconnectConnectionUseCase,
+    private readonly listUseCase: ListUserConnectionsUseCase,
   ) {}
 
   /**
-   * Loads the integration for `(userId, provider)` and returns it with
+   * Loads the connection for `(userId, provider)` and returns it with
    * decrypted tokens, or `null` if no row exists. Returns the row even
    * if `status !== 'active'` so callers can distinguish "never
    * connected" from "connected but broken" — gate on `status` yourself.
@@ -71,17 +71,17 @@ export class IntegrationsService {
   async findByUserAndProvider(
     userId: string,
     provider: string,
-  ): Promise<DecryptedIntegrationRow | null> {
-    const row = await this.integrations.findByUserIdAndProvider(userId, provider);
+  ): Promise<DecryptedConnectionRow | null> {
+    const row = await this.connections.findByUserIdAndProvider(userId, provider);
     if (!row) return null;
     return this.decrypt(row);
   }
 
   /**
-   * Lists a user's integrations newest-first, with ciphertexts stripped.
+   * Lists a user's connections newest-first, with ciphertexts stripped.
    * Safe to return to a frontend.
    */
-  async listByUser(userId: string): Promise<Array<Omit<Integration, 'accessTokenEncrypted' | 'refreshTokenEncrypted'>>> {
+  async listByUser(userId: string): Promise<Array<Omit<Connection, 'accessTokenEncrypted' | 'refreshTokenEncrypted'>>> {
     const rows = await this.listUseCase.execute(userId);
     return rows.map((row) => {
       const { accessTokenEncrypted: _accessTokenEncrypted, refreshTokenEncrypted: _refreshTokenEncrypted, ...safe } = row;
@@ -92,39 +92,39 @@ export class IntegrationsService {
   /**
    * Upserts a freshly-minted OAuth2 grant from the authorize-code
    * callback. Pass-through to `CreateOrUpdateFromOAuthGrantUseCase` —
-   * the input shape matches the auth subsystem's `IntegrationGrantInput`
-   * exactly so `IntegrationGrantSinkAdapter` can forward without
+   * the input shape matches the auth subsystem's `ConnectionGrantInput`
+   * exactly so `ConnectionGrantSinkAdapter` can forward without
    * mapping.
    */
-  async createOrUpdateFromOAuthGrant(input: IntegrationGrantInput): Promise<void> {
+  async createOrUpdateFromOAuthGrant(input: ConnectionGrantInput): Promise<void> {
     await this.createOrUpdateUseCase.execute(input);
   }
 
   /**
    * Flips status to `requires_reauth`. Called from `withAuthRetry`'s
-   * broken-integration handler.
+   * broken-connection handler.
    */
-  async markRequiresReauth(integrationId: string): Promise<void> {
-    await this.markReauthUseCase.execute(integrationId);
+  async markRequiresReauth(connectionId: string): Promise<void> {
+    await this.markReauthUseCase.execute(connectionId);
   }
 
   /**
    * User-initiated disconnect. Status → 'revoked', tokens cleared.
    */
-  async disconnect(integrationId: string): Promise<void> {
-    await this.disconnectUseCase.execute(integrationId);
+  async disconnect(connectionId: string): Promise<void> {
+    await this.disconnectUseCase.execute(connectionId);
   }
 
   /**
-   * Decrypts ciphertexts on a raw `Integration` row. Used internally
-   * by `findByUserAndProvider` and by `IntegrationReaderAdapter`.
+   * Decrypts ciphertexts on a raw `Connection` row. Used internally
+   * by `findByUserAndProvider` and by `ConnectionReaderAdapter`.
    *
    * Empty access tokens (e.g. revoked rows where the ciphertext was
    * cleared) decrypt to the empty string — matches
-   * `DecryptedIntegration.accessToken`'s "empty if never granted"
+   * `DecryptedConnection.accessToken`'s "empty if never granted"
    * contract.
    */
-  private async decrypt(row: Integration): Promise<DecryptedIntegrationRow> {
+  private async decrypt(row: Connection): Promise<DecryptedConnectionRow> {
     const accessToken = row.accessTokenEncrypted
       ? await this.encryption.decrypt(row.accessTokenEncrypted)
       : '';

package/examples/auth-integrations/runtime/{integrations → connections}/oauth/use-cases/create-or-update-from-oauth-grant.use-case.ts

@@ -2,10 +2,10 @@ import { Inject, Injectable } from '@nestjs/common';
 import {
   ENCRYPTION_KEY,
   type IEncryptionKey,
-  type IntegrationGrantInput,
+  type ConnectionGrantInput,
 } from '@pattern-stack/codegen/runtime/subsystems/auth';
-import { IntegrationService } from '../../integration.service';
-import type { Integration } from '../../integration.entity';
+import { ConnectionService } from '../../connection.service';
+import type { Connection } from '../../connection.entity';
 
 /**
  * Persists an OAuth2 grant from the authorize-code callback (initial
@@ -14,8 +14,8 @@ import type { Integration } from '../../integration.entity';
  *   - existing row → re-encrypt + persist tokens, status → 'active'
  *   - missing row  → insert a new row in 'active' status
  *
- * The input shape is exactly `IntegrationGrantInput` from the auth
- * subsystem so `IntegrationGrantSinkAdapter` can be a pass-through —
+ * The input shape is exactly `ConnectionGrantInput` from the auth
+ * subsystem so `ConnectionGrantSinkAdapter` can be a pass-through —
  * the port and use case share the same boundary type. Encryption is
  * applied here (inside the use case) before ciphertexts hit the row.
  *
@@ -27,18 +27,18 @@ import type { Integration } from '../../integration.entity';
 @Injectable()
 export class CreateOrUpdateFromOAuthGrantUseCase {
   constructor(
-    private readonly integrations: IntegrationService,
+    private readonly connections: ConnectionService,
     @Inject(ENCRYPTION_KEY) private readonly encryption: IEncryptionKey,
   ) {}
 
-  async execute(input: IntegrationGrantInput): Promise<Integration> {
+  async execute(input: ConnectionGrantInput): Promise<Connection> {
     const accessTokenEncrypted = await this.encryption.encrypt(input.accessToken);
     const refreshTokenEncrypted =
       input.refreshToken !== undefined
         ? await this.encryption.encrypt(input.refreshToken)
         : undefined;
 
-    const existing = await this.integrations.findByUserIdAndProvider(
+    const existing = await this.connections.findByUserIdAndProvider(
       input.userId,
       input.provider,
     );
@@ -57,17 +57,17 @@ export class CreateOrUpdateFromOAuthGrantUseCase {
     if (existing) {
       // Preserve the existing refresh-token ciphertext when the grant
       // didn't include a new refresh token (common on re-grants).
-      const patch: Partial<Integration> = {
+      const patch: Partial<Connection> = {
         ...baseRow,
         refreshTokenEncrypted:
           refreshTokenEncrypted !== undefined
             ? refreshTokenEncrypted
             : existing.refreshTokenEncrypted,
       };
-      return this.integrations.update(existing.id, patch);
+      return this.connections.update(existing.id, patch);
     }
 
-    return this.integrations.create({
+    return this.connections.create({
       ...baseRow,
       refreshTokenEncrypted: refreshTokenEncrypted ?? null,
     });

package/examples/auth-integrations/runtime/{integrations/oauth/use-cases/disconnect-integration.use-case.ts → connections/oauth/use-cases/disconnect-connection.use-case.ts}

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
-import { IntegrationService } from '../../integration.service';
-import type { Integration } from '../../integration.entity';
+import { ConnectionService } from '../../connection.service';
+import type { Connection } from '../../connection.entity';
 
 /**
  * User-initiated disconnect. Flips status to `revoked` and clears the
@@ -15,11 +15,11 @@ import type { Integration } from '../../integration.entity';
  * starter).
  */
 @Injectable()
-export class DisconnectIntegrationUseCase {
-  constructor(private readonly integrations: IntegrationService) {}
+export class DisconnectConnectionUseCase {
+  constructor(private readonly connections: ConnectionService) {}
 
-  async execute(integrationId: string): Promise<Integration> {
-    return this.integrations.update(integrationId, {
+  async execute(connectionId: string): Promise<Connection> {
+    return this.connections.update(connectionId, {
       status: 'revoked',
       accessTokenEncrypted: null,
       refreshTokenEncrypted: null,