@lssm/integration.runtime 0.0.0-canary-20251217083314 → 1.41.1

package/dist/index.d.mts

@@ -0,0 +1,267 @@
+import { SecretManagerServiceClient, protos } from "@google-cloud/secret-manager";
+import { ResolvedAppConfig, ResolvedIntegration } from "@lssm/lib.contracts/app-config/runtime";
+import { ConnectionStatus, IntegrationConnection, IntegrationConnectionHealth } from "@lssm/lib.contracts/integrations/connection";
+import { IntegrationSpec } from "@lssm/lib.contracts/integrations/spec";
+import { CallOptions } from "google-gax";
+
+//#region src/secrets/provider.d.ts
+type SecretReference = string;
+interface SecretValue {
+  data: Uint8Array;
+  version?: string;
+  metadata?: Record<string, string>;
+  retrievedAt: Date;
+}
+interface SecretFetchOptions {
+  version?: string;
+}
+type SecretPayloadEncoding = 'utf-8' | 'base64' | 'binary';
+interface SecretWritePayload {
+  data: string | Uint8Array;
+  encoding?: SecretPayloadEncoding;
+  contentType?: string;
+  labels?: Record<string, string>;
+}
+interface SecretRotationResult {
+  reference: SecretReference;
+  version: string;
+}
+interface SecretProvider {
+  readonly id: string;
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+}
+interface ParsedSecretUri {
+  provider: string;
+  path: string;
+  extras?: Record<string, string>;
+}
+declare class SecretProviderError extends Error {
+  readonly provider: string;
+  readonly reference: SecretReference;
+  readonly code: 'NOT_FOUND' | 'FORBIDDEN' | 'INVALID' | 'UNKNOWN';
+  readonly cause?: unknown;
+  constructor(params: {
+    message: string;
+    provider: string;
+    reference: SecretReference;
+    code?: SecretProviderError['code'];
+    cause?: unknown;
+  });
+}
+declare function parseSecretUri(reference: SecretReference): ParsedSecretUri;
+declare function normalizeSecretPayload(payload: SecretWritePayload): Uint8Array;
+//#endregion
+//#region src/runtime.d.ts
+interface IntegrationTraceMetadata {
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+}
+interface IntegrationTelemetryEvent {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  integrationKey: string;
+  integrationVersion: number;
+  connectionId: string;
+  status: 'success' | 'error';
+  durationMs?: number;
+  errorCode?: string;
+  errorMessage?: string;
+  occurredAt: Date;
+  metadata?: Record<string, string | number | boolean>;
+}
+interface IntegrationTelemetryEmitter {
+  record(event: IntegrationTelemetryEvent): Promise<void> | void;
+}
+type IntegrationInvocationStatus = 'success' | 'error';
+interface IntegrationContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  spec: IntegrationSpec;
+  connection: IntegrationConnection;
+  secretProvider: SecretProvider;
+  secretReference: string;
+  trace: IntegrationTraceMetadata;
+  config?: Record<string, unknown>;
+}
+interface IntegrationCallContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  slotId: string;
+  operation: string;
+}
+interface IntegrationCallError {
+  code: string;
+  message: string;
+  retryable: boolean;
+  cause?: unknown;
+}
+interface IntegrationCallResult<T> {
+  success: boolean;
+  data?: T;
+  error?: IntegrationCallError;
+  metadata: {
+    latencyMs: number;
+    connectionId: string;
+    ownershipMode: IntegrationConnection['ownershipMode'];
+    attempts: number;
+  };
+}
+interface IntegrationCallGuardOptions {
+  telemetry?: IntegrationTelemetryEmitter;
+  maxAttempts?: number;
+  backoffMs?: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+}
+declare class IntegrationCallGuard {
+  private readonly secretProvider;
+  private readonly telemetry?;
+  private readonly maxAttempts;
+  private readonly backoffMs;
+  private readonly shouldRetry;
+  private readonly sleep;
+  private readonly now;
+  constructor(secretProvider: SecretProvider, options?: IntegrationCallGuardOptions);
+  executeWithGuards<T>(slotId: string, operation: string, _input: unknown, resolvedConfig: ResolvedAppConfig, executor: (connection: IntegrationConnection, secrets: Record<string, string>) => Promise<T>): Promise<IntegrationCallResult<T>>;
+  private findIntegration;
+  private fetchSecrets;
+  private parseSecret;
+  private emitTelemetry;
+  private failure;
+  private makeContext;
+  private errorCodeFor;
+}
+declare function ensureConnectionReady(integration: ResolvedIntegration): void;
+declare function connectionStatusLabel(status: ConnectionStatus): string;
+//#endregion
+//#region src/health.d.ts
+interface IntegrationHealthCheckResult extends IntegrationConnectionHealth {
+  metadata?: Record<string, string>;
+}
+type IntegrationHealthCheckExecutor = (context: IntegrationContext) => Promise<void>;
+interface IntegrationHealthServiceOptions {
+  telemetry?: IntegrationTelemetryEmitter;
+  now?: () => Date;
+}
+declare class IntegrationHealthService {
+  private readonly telemetry?;
+  private readonly nowFn;
+  constructor(options?: IntegrationHealthServiceOptions);
+  check(context: IntegrationContext, executor: IntegrationHealthCheckExecutor): Promise<IntegrationHealthCheckResult>;
+  private emitTelemetry;
+}
+//#endregion
+//#region src/secrets/gcp-secret-manager.d.ts
+type SecretManagerClient = SecretManagerServiceClient;
+interface GcpSecretManagerProviderOptions {
+  projectId?: string;
+  client?: SecretManagerClient;
+  clientOptions?: ConstructorParameters<typeof SecretManagerServiceClient>[0];
+  defaultReplication?: protos.google.cloud.secretmanager.v1.IReplication;
+}
+declare class GcpSecretManagerProvider implements SecretProvider {
+  readonly id = "gcp-secret-manager";
+  private readonly client;
+  private readonly explicitProjectId?;
+  private readonly replication;
+  constructor(options?: GcpSecretManagerProviderOptions);
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: {
+    version?: string;
+  }, callOptions?: CallOptions): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private parseReference;
+  private buildNames;
+  private buildVersionName;
+  private ensureSecretExists;
+}
+//#endregion
+//#region src/secrets/env-secret-provider.d.ts
+interface EnvSecretProviderOptions {
+  /**
+   * Optional map to alias secret references to environment variable names.
+   * Useful when referencing secrets from other providers (e.g. gcp://...)
+   * while still allowing local overrides.
+   */
+  aliases?: Record<string, string>;
+}
+/**
+ * Environment-variable backed secret provider. Read-only by design.
+ * Allows overriding other secret providers by deriving environment variable
+ * names from secret references (or by using explicit aliases).
+ */
+declare class EnvSecretProvider implements SecretProvider {
+  readonly id = "env";
+  private readonly aliases;
+  constructor(options?: EnvSecretProviderOptions);
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference): Promise<SecretValue>;
+  setSecret(reference: SecretReference, _payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, _payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private resolveEnvKey;
+  private deriveEnvKey;
+  private forbiddenError;
+}
+//#endregion
+//#region src/secrets/manager.d.ts
+interface RegisterOptions {
+  /**
+   * Larger priority values are attempted first. Defaults to 0.
+   */
+  priority?: number;
+}
+interface SecretProviderManagerOptions {
+  /**
+   * Override manager identifier. Defaults to "secret-provider-manager".
+   */
+  id?: string;
+  /**
+   * Providers to pre-register. They are registered in array order with
+   * descending priority (first entry wins ties).
+   */
+  providers?: {
+    provider: SecretProvider;
+    priority?: number;
+  }[];
+}
+/**
+ * Composite secret provider that delegates to registered providers.
+ * Providers are attempted in order of descending priority, respecting the
+ * registration order for ties. This enables privileged overrides (e.g.
+ * environment variables) while still supporting durable backends like GCP
+ * Secret Manager.
+ */
+declare class SecretProviderManager implements SecretProvider {
+  readonly id: string;
+  private readonly providers;
+  private registrationCounter;
+  constructor(options?: SecretProviderManagerOptions);
+  register(provider: SecretProvider, options?: RegisterOptions): this;
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: SecretFetchOptions$1): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private delegateToFirst;
+  private composeError;
+}
+type SecretFetchOptions$1 = Parameters<SecretProvider['getSecret']>[1];
+//#endregion
+export { EnvSecretProvider, GcpSecretManagerProvider, IntegrationCallContext, IntegrationCallError, IntegrationCallGuard, IntegrationCallGuardOptions, IntegrationCallResult, IntegrationContext, IntegrationHealthCheckExecutor, IntegrationHealthCheckResult, IntegrationHealthService, IntegrationHealthServiceOptions, IntegrationInvocationStatus, IntegrationTelemetryEmitter, IntegrationTelemetryEvent, IntegrationTraceMetadata, ParsedSecretUri, SecretFetchOptions, SecretPayloadEncoding, SecretProvider, SecretProviderError, SecretProviderManager, SecretProviderManagerOptions, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload, connectionStatusLabel, ensureConnectionReady, normalizeSecretPayload, parseSecretUri };