@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/declarations.ts

@@ -0,0 +1,1119 @@
+/**
+ * Integration declaration functions and types.
+ *
+ * This module provides declaration functions for specifying integrations
+ * upfront in the API config. This enables:
+ * - Single declaration of integration IDs
+ * - Full type safety on ctx.integrations
+ * - Upfront authentication before API execution
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres, slack } from '@superblocksteam/sdk-api';
+ *
+ * // Store integration IDs in constants with descriptive names
+ * const PROD_POSTGRES = 'a1b2c3d4-uuid';
+ * const OPS_SLACK = 'e5f6g7h8-uuid';
+ *
+ * export default api({
+ *   integrations: {
+ *     pg: postgres(PROD_POSTGRES),
+ *     notifier: slack(OPS_SLACK),
+ *   },
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ name: z.string() }),
+ *   async run(ctx) {
+ *     const users = await ctx.integrations.pg.query(...);
+ *     await ctx.integrations.notifier.postMessage(...);
+ *     return { name: users[0].name };
+ *   },
+ * });
+ * ```
+ */
+
+import type { PostgresClient } from './postgres/index.js';
+import type { SlackClient } from './slack/index.js';
+import type { OpenAIClient } from './openai_v2/index.js';
+import type { AnthropicClient } from './anthropic/index.js';
+import type { StripeClient } from './stripe/index.js';
+import type { GitHubClient } from './github/index.js';
+import type { NotionClient } from './notion/index.js';
+import type { SnowflakeClient } from './snowflake/index.js';
+import type { AirtableClient } from './airtable/index.js';
+import type { AsanaClient } from './asana/index.js';
+import type { BitbucketClient } from './bitbucket/index.js';
+import type { BoxClient } from './box/index.js';
+import type { CircleCIClient } from './circleci/index.js';
+import type { CohereClient } from './cohere/index.js';
+import type { ConfluenceClient } from './confluence/index.js';
+import type { DatadogClient } from './datadog/index.js';
+import type { DropboxClient } from './dropbox/index.js';
+import type { ElasticSearchClient } from './elasticsearch/index.js';
+import type { FireworksClient } from './fireworks/index.js';
+import type { FrontClient } from './front/index.js';
+import type { GeminiClient } from './gemini/index.js';
+import type { GoogleAnalyticsClient } from './googleanalytics/index.js';
+import type { GoogleDriveClient } from './googledrive/index.js';
+import type { GroqClient } from './groq/index.js';
+import type { HubSpotClient } from './hubspot/index.js';
+import type { IntercomClient } from './intercom/index.js';
+import type { JiraClient } from './jira/index.js';
+import type { LaunchDarklyClient } from './launchdarkly/index.js';
+import type { MistralClient } from './mistral/index.js';
+import type { PagerDutyClient } from './pagerduty/index.js';
+import type { PerplexityClient } from './perplexity/index.js';
+import type { SegmentClient } from './segment/index.js';
+import type { SendGridClient } from './sendgrid/index.js';
+import type { StabilityAIClient } from './stabilityai/index.js';
+import type { TwilioClient } from './twilio/index.js';
+import type { ZendeskClient } from './zendesk/index.js';
+import type { ZoomClient } from './zoom/index.js';
+import type { GraphQLClient } from './graphql/index.js';
+import type { MySQLClient } from './mysql/index.js';
+import type { MariaDBClient } from './mariadb/index.js';
+import type { MSSQLClient } from './mssql/index.js';
+import type { CockroachDBClient } from './cockroachdb/index.js';
+import type { OracleDBClient } from './oracledb/index.js';
+import type { RedshiftClient } from './redshift/index.js';
+import type { AthenaClient } from './athena/index.js';
+import type { DatabricksClient } from './databricks/index.js';
+import type { BigQueryClient } from './bigquery/index.js';
+import type { MongoDBClient } from './mongodb/index.js';
+import type { DynamoDBClient } from './dynamodb/index.js';
+import type { CosmosDBClient } from './cosmosdb/index.js';
+import type { CouchbaseClient } from './couchbase/index.js';
+import type { S3Client } from './s3/index.js';
+import type { GCSClient } from './gcs/index.js';
+import type { GoogleSheetsClient } from './gsheets/index.js';
+import type { KafkaClient } from './kafka/index.js';
+import type { KinesisClient } from './kinesis/index.js';
+import type { SalesforceClient } from './salesforce/index.js';
+import type { RedisClient } from './redis/index.js';
+import type { SuperblocksOCRClient } from './superblocks-ocr/index.js';
+import type { LakebaseClient } from './lakebase/index.js';
+import type { SmtpClient } from './smtp/index.js';
+import type { PythonClient } from './python/index.js';
+
+// -----------------------------------------------------------------------------
+// Base Types
+// -----------------------------------------------------------------------------
+
+/**
+ * Base type for all integration references.
+ *
+ * An IntegrationRef represents a declared integration that will be available
+ * at runtime via `ctx.integrations`. The TClient type parameter enables
+ * type inference for the actual client type.
+ *
+ * @template TPluginId - The plugin type identifier (e.g., 'postgres', 'slack')
+ * @template TClient - The client interface type (e.g., PostgresClient)
+ */
+export interface IntegrationRef<TPluginId extends string, TClient> {
+  /** The plugin type identifier */
+  readonly pluginId: TPluginId;
+
+  /** The integration ID (UUID) */
+  readonly id: string;
+
+  /**
+   * Phantom type marker for client inference.
+   * This is never used at runtime - it exists purely for TypeScript
+   * to infer the correct client type.
+   */
+  readonly __clientType?: TClient;
+}
+
+/**
+ * Helper function to create an integration reference.
+ *
+ * @internal
+ */
+function createRef<TPluginId extends string, TClient>(
+  pluginId: TPluginId,
+  id: string,
+): IntegrationRef<TPluginId, TClient> {
+  return { pluginId, id };
+}
+
+// -----------------------------------------------------------------------------
+// Integration Reference Types
+// -----------------------------------------------------------------------------
+
+/** Reference to a PostgreSQL integration */
+export type PostgresRef = IntegrationRef<'postgres', PostgresClient>;
+
+/** Reference to a Slack integration */
+export type SlackRef = IntegrationRef<'slack', SlackClient>;
+
+/** Reference to an OpenAI integration */
+export type OpenAIRef = IntegrationRef<'openai_v2', OpenAIClient>;
+
+/** Reference to an Anthropic integration */
+export type AnthropicRef = IntegrationRef<'anthropic', AnthropicClient>;
+
+/** Reference to a Stripe integration */
+export type StripeRef = IntegrationRef<'stripe', StripeClient>;
+
+/** Reference to a GitHub integration */
+export type GitHubRef = IntegrationRef<'github', GitHubClient>;
+
+/** Reference to a Notion integration */
+export type NotionRef = IntegrationRef<'notion', NotionClient>;
+
+/** Reference to a Snowflake integration */
+export type SnowflakeRef = IntegrationRef<'snowflake', SnowflakeClient>;
+
+/** Reference to an Airtable integration */
+export type AirtableRef = IntegrationRef<'airtable', AirtableClient>;
+
+/** Reference to an Asana integration */
+export type AsanaRef = IntegrationRef<'asana', AsanaClient>;
+
+/** Reference to a Bitbucket integration */
+export type BitbucketRef = IntegrationRef<'bitbucket', BitbucketClient>;
+
+/** Reference to a Box integration */
+export type BoxRef = IntegrationRef<'box', BoxClient>;
+
+/** Reference to a CircleCI integration */
+export type CircleCIRef = IntegrationRef<'circleci', CircleCIClient>;
+
+/** Reference to a Cohere integration */
+export type CohereRef = IntegrationRef<'cohere', CohereClient>;
+
+/** Reference to a Confluence integration */
+export type ConfluenceRef = IntegrationRef<'confluence', ConfluenceClient>;
+
+/** Reference to a Datadog integration */
+export type DatadogRef = IntegrationRef<'datadog', DatadogClient>;
+
+/** Reference to a Dropbox integration */
+export type DropboxRef = IntegrationRef<'dropbox', DropboxClient>;
+
+/** Reference to an ElasticSearch integration */
+export type ElasticSearchRef = IntegrationRef<'elasticsearch', ElasticSearchClient>;
+
+/** Reference to a Fireworks integration */
+export type FireworksRef = IntegrationRef<'fireworks', FireworksClient>;
+
+/** Reference to a Front integration */
+export type FrontRef = IntegrationRef<'front', FrontClient>;
+
+/** Reference to a Gemini integration */
+export type GeminiRef = IntegrationRef<'gemini', GeminiClient>;
+
+/** Reference to a Google Analytics integration */
+export type GoogleAnalyticsRef = IntegrationRef<'googleanalytics', GoogleAnalyticsClient>;
+
+/** Reference to a Google Drive integration */
+export type GoogleDriveRef = IntegrationRef<'googledrive', GoogleDriveClient>;
+
+/** Reference to a Groq integration */
+export type GroqRef = IntegrationRef<'groq', GroqClient>;
+
+/** Reference to a HubSpot integration */
+export type HubSpotRef = IntegrationRef<'hubspot', HubSpotClient>;
+
+/** Reference to an Intercom integration */
+export type IntercomRef = IntegrationRef<'intercom', IntercomClient>;
+
+/** Reference to a Jira integration */
+export type JiraRef = IntegrationRef<'jira', JiraClient>;
+
+/** Reference to a LaunchDarkly integration */
+export type LaunchDarklyRef = IntegrationRef<'launchdarkly', LaunchDarklyClient>;
+
+/** Reference to a Mistral integration */
+export type MistralRef = IntegrationRef<'mistral', MistralClient>;
+
+/** Reference to a PagerDuty integration */
+export type PagerDutyRef = IntegrationRef<'pagerduty', PagerDutyClient>;
+
+/** Reference to a Perplexity integration */
+export type PerplexityRef = IntegrationRef<'perplexity', PerplexityClient>;
+
+/** Reference to a Segment integration */
+export type SegmentRef = IntegrationRef<'segment', SegmentClient>;
+
+/** Reference to a SendGrid integration */
+export type SendGridRef = IntegrationRef<'sendgrid', SendGridClient>;
+
+/** Reference to a StabilityAI integration */
+export type StabilityAIRef = IntegrationRef<'stabilityai', StabilityAIClient>;
+
+/** Reference to a Twilio integration */
+export type TwilioRef = IntegrationRef<'twilio', TwilioClient>;
+
+/** Reference to a Zendesk integration */
+export type ZendeskRef = IntegrationRef<'zendesk', ZendeskClient>;
+
+/** Reference to a Zoom integration */
+export type ZoomRef = IntegrationRef<'zoom', ZoomClient>;
+
+/** Reference to a GraphQL integration */
+export type GraphQLRef = IntegrationRef<'graphqlintegration', GraphQLClient>;
+
+/** Reference to a MySQL integration */
+export type MySQLRef = IntegrationRef<'mysql', MySQLClient>;
+
+/** Reference to a MariaDB integration */
+export type MariaDBRef = IntegrationRef<'mariadb', MariaDBClient>;
+
+/** Reference to a MSSQL integration */
+export type MSSQLRef = IntegrationRef<'mssql', MSSQLClient>;
+
+/** Reference to a CockroachDB integration */
+export type CockroachDBRef = IntegrationRef<'cockroachdb', CockroachDBClient>;
+
+/** Reference to an OracleDB integration */
+export type OracleDBRef = IntegrationRef<'oracledb', OracleDBClient>;
+
+/** Reference to a Redshift integration */
+export type RedshiftRef = IntegrationRef<'redshift', RedshiftClient>;
+
+/** Reference to an Athena integration */
+export type AthenaRef = IntegrationRef<'athena', AthenaClient>;
+
+/** Reference to a Databricks integration */
+export type DatabricksRef = IntegrationRef<'databricks', DatabricksClient>;
+
+/** Reference to a BigQuery integration */
+export type BigQueryRef = IntegrationRef<'bigquery', BigQueryClient>;
+
+/** Reference to a MongoDB integration */
+export type MongoDBRef = IntegrationRef<'mongodb', MongoDBClient>;
+
+/** Reference to a DynamoDB integration */
+export type DynamoDBRef = IntegrationRef<'dynamodb', DynamoDBClient>;
+
+/** Reference to a CosmosDB integration */
+export type CosmosDBRef = IntegrationRef<'cosmosdb', CosmosDBClient>;
+
+/** Reference to a Couchbase integration */
+export type CouchbaseRef = IntegrationRef<'couchbase', CouchbaseClient>;
+
+/** Reference to an S3 integration */
+export type S3Ref = IntegrationRef<'s3', S3Client>;
+
+/** Reference to a GCS integration */
+export type GCSRef = IntegrationRef<'gcs', GCSClient>;
+
+/** Reference to a Google Sheets integration */
+export type GoogleSheetsRef = IntegrationRef<'gsheets', GoogleSheetsClient>;
+
+/** Reference to a Kafka integration */
+export type KafkaRef = IntegrationRef<'kafka', KafkaClient>;
+
+/** Reference to a Kinesis integration */
+export type KinesisRef = IntegrationRef<'kinesis', KinesisClient>;
+
+/** Reference to a Salesforce integration */
+export type SalesforceRef = IntegrationRef<'salesforce', SalesforceClient>;
+
+/** Reference to a Redis integration */
+export type RedisRef = IntegrationRef<'redis', RedisClient>;
+
+/** Reference to a Superblocks OCR integration */
+export type SuperblocksOCRRef = IntegrationRef<'superblocks-ocr', SuperblocksOCRClient>;
+
+/** Reference to a Python integration */
+export type PythonRef = IntegrationRef<'python', PythonClient>;
+
+/** Reference to a Confluent integration (Kafka-compatible) */
+export type ConfluentRef = IntegrationRef<'confluent', KafkaClient>;
+
+/** Reference to a Redpanda integration (Kafka-compatible) */
+export type RedpandaRef = IntegrationRef<'redpanda', KafkaClient>;
+
+/** Reference to a Lakebase integration */
+export type LakebaseRef = IntegrationRef<'lakebase', LakebaseClient>;
+
+/** Reference to an SMTP integration */
+export type SmtpRef = IntegrationRef<'smtp', SmtpClient>;
+
+// -----------------------------------------------------------------------------
+// Declaration Functions
+// -----------------------------------------------------------------------------
+
+/**
+ * Declare a PostgreSQL integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ *
+ * @example
+ * ```typescript
+ * import { api, z, postgres } from '@superblocksteam/sdk-api';
+ *
+ * const PROD_POSTGRES = 'a1b2c3d4-uuid';
+ *
+ * export default api({
+ *   integrations: {
+ *     db: postgres(PROD_POSTGRES),
+ *   },
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ name: z.string() }),
+ *   async run(ctx, { userId }) {
+ *     const users = await ctx.integrations.db.query(
+ *       'SELECT * FROM users WHERE id = $1',
+ *       z.object({ id: z.string(), name: z.string() }),
+ *       [userId]
+ *     );
+ *     return { name: users[0].name };
+ *   },
+ * });
+ * ```
+ */
+export function postgres(id: string): PostgresRef {
+  return createRef<'postgres', PostgresClient>('postgres', id);
+}
+
+/**
+ * Declare a Slack integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ *
+ * @example
+ * ```typescript
+ * import { api, z, slack } from '@superblocksteam/sdk-api';
+ *
+ * const OPS_SLACK = 'e5f6g7h8-uuid';
+ *
+ * export default api({
+ *   integrations: {
+ *     notifier: slack(OPS_SLACK),
+ *   },
+ *   input: z.object({ message: z.string() }),
+ *   output: z.object({ sent: z.boolean() }),
+ *   async run(ctx, { message }) {
+ *     await ctx.integrations.notifier.postMessage({
+ *       channel: '#alerts',
+ *       text: message,
+ *     });
+ *     return { sent: true };
+ *   },
+ * });
+ * ```
+ */
+export function slack(id: string): SlackRef {
+  return createRef<'slack', SlackClient>('slack', id);
+}
+
+/**
+ * Declare an OpenAI integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function openai(id: string): OpenAIRef {
+  return createRef<'openai_v2', OpenAIClient>('openai_v2', id);
+}
+
+/**
+ * Declare an Anthropic integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function anthropic(id: string): AnthropicRef {
+  return createRef<'anthropic', AnthropicClient>('anthropic', id);
+}
+
+/**
+ * Declare a Stripe integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function stripe(id: string): StripeRef {
+  return createRef<'stripe', StripeClient>('stripe', id);
+}
+
+/**
+ * Declare a GitHub integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function github(id: string): GitHubRef {
+  return createRef<'github', GitHubClient>('github', id);
+}
+
+/**
+ * Declare a Notion integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function notion(id: string): NotionRef {
+  return createRef<'notion', NotionClient>('notion', id);
+}
+
+/**
+ * Declare a Snowflake integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function snowflake(id: string): SnowflakeRef {
+  return createRef<'snowflake', SnowflakeClient>('snowflake', id);
+}
+
+/**
+ * Declare an Airtable integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function airtable(id: string): AirtableRef {
+  return createRef<'airtable', AirtableClient>('airtable', id);
+}
+
+/**
+ * Declare an Asana integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function asana(id: string): AsanaRef {
+  return createRef<'asana', AsanaClient>('asana', id);
+}
+
+/**
+ * Declare a Bitbucket integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function bitbucket(id: string): BitbucketRef {
+  return createRef<'bitbucket', BitbucketClient>('bitbucket', id);
+}
+
+/**
+ * Declare a Box integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function box(id: string): BoxRef {
+  return createRef<'box', BoxClient>('box', id);
+}
+
+/**
+ * Declare a CircleCI integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function circleci(id: string): CircleCIRef {
+  return createRef<'circleci', CircleCIClient>('circleci', id);
+}
+
+/**
+ * Declare a Cohere integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function cohere(id: string): CohereRef {
+  return createRef<'cohere', CohereClient>('cohere', id);
+}
+
+/**
+ * Declare a Confluence integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function confluence(id: string): ConfluenceRef {
+  return createRef<'confluence', ConfluenceClient>('confluence', id);
+}
+
+/**
+ * Declare a Datadog integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function datadog(id: string): DatadogRef {
+  return createRef<'datadog', DatadogClient>('datadog', id);
+}
+
+/**
+ * Declare a Dropbox integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function dropbox(id: string): DropboxRef {
+  return createRef<'dropbox', DropboxClient>('dropbox', id);
+}
+
+/**
+ * Declare an ElasticSearch integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function elasticsearch(id: string): ElasticSearchRef {
+  return createRef<'elasticsearch', ElasticSearchClient>('elasticsearch', id);
+}
+
+/**
+ * Declare a Fireworks integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function fireworks(id: string): FireworksRef {
+  return createRef<'fireworks', FireworksClient>('fireworks', id);
+}
+
+/**
+ * Declare a Front integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function front(id: string): FrontRef {
+  return createRef<'front', FrontClient>('front', id);
+}
+
+/**
+ * Declare a Gemini integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function gemini(id: string): GeminiRef {
+  return createRef<'gemini', GeminiClient>('gemini', id);
+}
+
+/**
+ * Declare a Google Analytics integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function googleAnalytics(id: string): GoogleAnalyticsRef {
+  return createRef<'googleanalytics', GoogleAnalyticsClient>('googleanalytics', id);
+}
+
+/**
+ * Declare a Google Drive integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function googleDrive(id: string): GoogleDriveRef {
+  return createRef<'googledrive', GoogleDriveClient>('googledrive', id);
+}
+
+/**
+ * Declare a Groq integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function groq(id: string): GroqRef {
+  return createRef<'groq', GroqClient>('groq', id);
+}
+
+/**
+ * Declare a HubSpot integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function hubspot(id: string): HubSpotRef {
+  return createRef<'hubspot', HubSpotClient>('hubspot', id);
+}
+
+/**
+ * Declare an Intercom integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function intercom(id: string): IntercomRef {
+  return createRef<'intercom', IntercomClient>('intercom', id);
+}
+
+/**
+ * Declare a Jira integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function jira(id: string): JiraRef {
+  return createRef<'jira', JiraClient>('jira', id);
+}
+
+/**
+ * Declare a LaunchDarkly integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function launchDarkly(id: string): LaunchDarklyRef {
+  return createRef<'launchdarkly', LaunchDarklyClient>('launchdarkly', id);
+}
+
+/**
+ * Declare a Mistral integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function mistral(id: string): MistralRef {
+  return createRef<'mistral', MistralClient>('mistral', id);
+}
+
+/**
+ * Declare a PagerDuty integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function pagerDuty(id: string): PagerDutyRef {
+  return createRef<'pagerduty', PagerDutyClient>('pagerduty', id);
+}
+
+/**
+ * Declare a Perplexity integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function perplexity(id: string): PerplexityRef {
+  return createRef<'perplexity', PerplexityClient>('perplexity', id);
+}
+
+/**
+ * Declare a Segment integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function segment(id: string): SegmentRef {
+  return createRef<'segment', SegmentClient>('segment', id);
+}
+
+/**
+ * Declare a SendGrid integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function sendGrid(id: string): SendGridRef {
+  return createRef<'sendgrid', SendGridClient>('sendgrid', id);
+}
+
+/**
+ * Declare a StabilityAI integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function stabilityAI(id: string): StabilityAIRef {
+  return createRef<'stabilityai', StabilityAIClient>('stabilityai', id);
+}
+
+/**
+ * Declare a Twilio integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function twilio(id: string): TwilioRef {
+  return createRef<'twilio', TwilioClient>('twilio', id);
+}
+
+/**
+ * Declare a Zendesk integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function zendesk(id: string): ZendeskRef {
+  return createRef<'zendesk', ZendeskClient>('zendesk', id);
+}
+
+/**
+ * Declare a Zoom integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function zoom(id: string): ZoomRef {
+  return createRef<'zoom', ZoomClient>('zoom', id);
+}
+
+/**
+ * Declare a GraphQL integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function graphql(id: string): GraphQLRef {
+  return createRef<'graphqlintegration', GraphQLClient>('graphqlintegration', id);
+}
+
+/**
+ * Declare a MySQL integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function mysql(id: string): MySQLRef {
+  return createRef<'mysql', MySQLClient>('mysql', id);
+}
+
+/**
+ * Declare a MariaDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function mariadb(id: string): MariaDBRef {
+  return createRef<'mariadb', MariaDBClient>('mariadb', id);
+}
+
+/**
+ * Declare a MSSQL integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function mssql(id: string): MSSQLRef {
+  return createRef<'mssql', MSSQLClient>('mssql', id);
+}
+
+/**
+ * Declare a CockroachDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function cockroachdb(id: string): CockroachDBRef {
+  return createRef<'cockroachdb', CockroachDBClient>('cockroachdb', id);
+}
+
+/**
+ * Declare an OracleDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function oracledb(id: string): OracleDBRef {
+  return createRef<'oracledb', OracleDBClient>('oracledb', id);
+}
+
+/**
+ * Declare a Redshift integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function redshift(id: string): RedshiftRef {
+  return createRef<'redshift', RedshiftClient>('redshift', id);
+}
+
+/**
+ * Declare an Athena integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function athena(id: string): AthenaRef {
+  return createRef<'athena', AthenaClient>('athena', id);
+}
+
+/**
+ * Declare a Databricks integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function databricks(id: string): DatabricksRef {
+  return createRef<'databricks', DatabricksClient>('databricks', id);
+}
+
+/**
+ * Declare a BigQuery integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function bigquery(id: string): BigQueryRef {
+  return createRef<'bigquery', BigQueryClient>('bigquery', id);
+}
+
+/**
+ * Declare a MongoDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function mongodb(id: string): MongoDBRef {
+  return createRef<'mongodb', MongoDBClient>('mongodb', id);
+}
+
+/**
+ * Declare a DynamoDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function dynamodb(id: string): DynamoDBRef {
+  return createRef<'dynamodb', DynamoDBClient>('dynamodb', id);
+}
+
+/**
+ * Declare a CosmosDB integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function cosmosdb(id: string): CosmosDBRef {
+  return createRef<'cosmosdb', CosmosDBClient>('cosmosdb', id);
+}
+
+/**
+ * Declare a Couchbase integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function couchbase(id: string): CouchbaseRef {
+  return createRef<'couchbase', CouchbaseClient>('couchbase', id);
+}
+
+/**
+ * Declare an S3 integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function s3(id: string): S3Ref {
+  return createRef<'s3', S3Client>('s3', id);
+}
+
+/**
+ * Declare a GCS (Google Cloud Storage) integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function gcs(id: string): GCSRef {
+  return createRef<'gcs', GCSClient>('gcs', id);
+}
+
+/**
+ * Declare a Google Sheets integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function googleSheets(id: string): GoogleSheetsRef {
+  return createRef<'gsheets', GoogleSheetsClient>('gsheets', id);
+}
+
+/**
+ * Declare a Kafka integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function kafka(id: string): KafkaRef {
+  return createRef<'kafka', KafkaClient>('kafka', id);
+}
+
+/**
+ * Declare a Kinesis integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function kinesis(id: string): KinesisRef {
+  return createRef<'kinesis', KinesisClient>('kinesis', id);
+}
+
+/**
+ * Declare a Salesforce integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function salesforce(id: string): SalesforceRef {
+  return createRef<'salesforce', SalesforceClient>('salesforce', id);
+}
+
+/**
+ * Declare a Redis integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function redis(id: string): RedisRef {
+  return createRef<'redis', RedisClient>('redis', id);
+}
+
+/**
+ * Declare a Superblocks OCR integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function superblocksOcr(id: string): SuperblocksOCRRef {
+  return createRef<'superblocks-ocr', SuperblocksOCRClient>('superblocks-ocr', id);
+}
+
+/**
+ * Declare a Python integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function python(id: string): PythonRef {
+  return createRef<'python', PythonClient>('python', id);
+}
+
+/**
+ * Declare a Confluent integration (Kafka-compatible).
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function confluent(id: string): ConfluentRef {
+  return createRef<'confluent', KafkaClient>('confluent', id);
+}
+
+/**
+ * Declare a Redpanda integration (Kafka-compatible).
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function redpanda(id: string): RedpandaRef {
+  return createRef<'redpanda', KafkaClient>('redpanda', id);
+}
+
+/**
+ * Declare a Lakebase integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function lakebase(id: string): LakebaseRef {
+  return createRef<'lakebase', LakebaseClient>('lakebase', id);
+}
+
+/**
+ * Declare an SMTP integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function smtp(id: string): SmtpRef {
+  return createRef<'smtp', SmtpClient>('smtp', id);
+}
+
+// -----------------------------------------------------------------------------
+// Type Utilities
+// -----------------------------------------------------------------------------
+
+/**
+ * Union of all possible integration reference types.
+ */
+export type AnyIntegrationRef = IntegrationRef<string, unknown>;
+
+/**
+ * Extract the client type from an integration reference.
+ *
+ * @example
+ * ```typescript
+ * type PgClient = ClientFromRef<PostgresRef>; // PostgresClient
+ * ```
+ */
+export type ClientFromRef<T> = T extends IntegrationRef<string, infer C> ? C : never;
+
+/**
+ * Map of integration keys to their client types.
+ *
+ * This type transforms a record of integration references into a record
+ * of their corresponding client types, enabling type-safe access via
+ * `ctx.integrations`.
+ *
+ * @example
+ * ```typescript
+ * type Integrations = IntegrationsMap<{
+ *   pg: PostgresRef;
+ *   notifier: SlackRef;
+ * }>;
+ * // => { pg: PostgresClient; notifier: SlackClient }
+ * ```
+ */
+export type IntegrationsMap<T extends Record<string, AnyIntegrationRef>> = {
+  [K in keyof T]: ClientFromRef<T[K]>;
+};
+
+/**
+ * Serialized integration declaration for runtime use.
+ *
+ * This is the format used by CompiledApi.integrations to list declared
+ * integrations for upfront authentication.
+ */
+export interface IntegrationDeclaration {
+  /** User-defined key in the integrations object */
+  readonly key: string;
+
+  /** The plugin type identifier */
+  readonly pluginId: string;
+
+  /** The integration ID (UUID) */
+  readonly id: string;
+}
+
+/**
+ * Extract integration declarations from an integrations config object.
+ *
+ * @param integrations - The integrations object from ApiConfig
+ * @returns Array of integration declarations for runtime use
+ */
+export function extractIntegrationDeclarations(
+  integrations: Record<string, AnyIntegrationRef> | undefined,
+): IntegrationDeclaration[] {
+  if (!integrations) {
+    return [];
+  }
+
+  return Object.entries(integrations).map(([key, ref]) => ({
+    key,
+    pluginId: ref.pluginId,
+    id: ref.id,
+  }));
+}
+
+/**
+ * Get integration declarations from an API object.
+ *
+ * Handles APIs from different sources:
+ * - CompiledApi from api(): integrations is already IntegrationDeclaration[]
+ * - Bundle output: integrations may be undefined (tree-shaken or omitted)
+ * - Raw config object: integrations is Record<string, IntegrationRef>
+ *
+ * @param api - API object with optional integrations field
+ * @returns Array of integration declarations for runtime use
+ */
+export function getIntegrationDeclarations(api: { integrations?: unknown }): IntegrationDeclaration[] {
+  const integrations = api.integrations;
+  if (integrations === undefined || integrations === null) {
+    return [];
+  }
+  if (Array.isArray(integrations)) {
+    return integrations as IntegrationDeclaration[];
+  }
+  return extractIntegrationDeclarations(integrations as Record<string, AnyIntegrationRef>);
+}