@superblocksteam/sdk-api 0.0.4

package/src/integrations/declarations.ts

@@ -0,0 +1,1282 @@
+/**
+ * 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 { SnowflakeCortexClient } from "./snowflakecortex/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 { SnowflakePostgresClient } from "./snowflakepostgres/index.js";
+import type { SmtpClient } from "./smtp/index.js";
+import type { RestApiIntegrationPluginClient } from "./restapiintegration/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;
+}
+
+/**
+ * Rejects the broad `string` type while still accepting string literal types.
+ * This keeps integration IDs statically analyzable by the build pipeline.
+ */
+type LiteralString<T extends string> = string extends T ? never : T;
+
+/**
+ * Helper function to create an integration reference.
+ *
+ * @internal
+ */
+function createRef<TPluginId extends string, TClient, TId extends string>(
+  pluginId: TPluginId,
+  id: LiteralString<TId>,
+): 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 a Snowflake Cortex integration */
+export type SnowflakeCortexRef = IntegrationRef<
+  "snowflakecortex",
+  SnowflakeCortexClient
+>;
+
+/** 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 a Snowflake Postgres integration */
+export type SnowflakePostgresRef = IntegrationRef<
+  "snowflakepostgres",
+  SnowflakePostgresClient
+>;
+
+/** Reference to an SMTP integration */
+export type SmtpRef = IntegrationRef<"smtp", SmtpClient>;
+
+/** Reference to a REST API Integration */
+export type RestApiIntegrationRef = IntegrationRef<
+  "restapiintegration",
+  RestApiIntegrationPluginClient
+>;
+
+// -----------------------------------------------------------------------------
+// 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<T extends string>(id: LiteralString<T>): PostgresRef {
+  return createRef<"postgres", PostgresClient, T>("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<T extends string>(id: LiteralString<T>): SlackRef {
+  return createRef<"slack", SlackClient, T>("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<T extends string>(id: LiteralString<T>): OpenAIRef {
+  return createRef<"openai_v2", OpenAIClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): AnthropicRef {
+  return createRef<"anthropic", AnthropicClient, T>("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<T extends string>(id: LiteralString<T>): StripeRef {
+  return createRef<"stripe", StripeClient, T>("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<T extends string>(id: LiteralString<T>): GitHubRef {
+  return createRef<"github", GitHubClient, T>("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<T extends string>(id: LiteralString<T>): NotionRef {
+  return createRef<"notion", NotionClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): SnowflakeRef {
+  return createRef<"snowflake", SnowflakeClient, T>("snowflake", id);
+}
+
+/**
+ * Declare a Snowflake Cortex integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function snowflakeCortex<T extends string>(
+  id: LiteralString<T>,
+): SnowflakeCortexRef {
+  return createRef<"snowflakecortex", SnowflakeCortexClient, T>(
+    "snowflakecortex",
+    id,
+  );
+}
+
+/**
+ * Declare an Airtable integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function airtable<T extends string>(id: LiteralString<T>): AirtableRef {
+  return createRef<"airtable", AirtableClient, T>("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<T extends string>(id: LiteralString<T>): AsanaRef {
+  return createRef<"asana", AsanaClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): BitbucketRef {
+  return createRef<"bitbucket", BitbucketClient, T>("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<T extends string>(id: LiteralString<T>): BoxRef {
+  return createRef<"box", BoxClient, T>("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<T extends string>(id: LiteralString<T>): CircleCIRef {
+  return createRef<"circleci", CircleCIClient, T>("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<T extends string>(id: LiteralString<T>): CohereRef {
+  return createRef<"cohere", CohereClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): ConfluenceRef {
+  return createRef<"confluence", ConfluenceClient, T>("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<T extends string>(id: LiteralString<T>): DatadogRef {
+  return createRef<"datadog", DatadogClient, T>("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<T extends string>(id: LiteralString<T>): DropboxRef {
+  return createRef<"dropbox", DropboxClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): ElasticSearchRef {
+  return createRef<"elasticsearch", ElasticSearchClient, T>(
+    "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<T extends string>(
+  id: LiteralString<T>,
+): FireworksRef {
+  return createRef<"fireworks", FireworksClient, T>("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<T extends string>(id: LiteralString<T>): FrontRef {
+  return createRef<"front", FrontClient, T>("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<T extends string>(id: LiteralString<T>): GeminiRef {
+  return createRef<"gemini", GeminiClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): GoogleAnalyticsRef {
+  return createRef<"googleanalytics", GoogleAnalyticsClient, T>(
+    "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<T extends string>(
+  id: LiteralString<T>,
+): GoogleDriveRef {
+  return createRef<"googledrive", GoogleDriveClient, T>("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<T extends string>(id: LiteralString<T>): GroqRef {
+  return createRef<"groq", GroqClient, T>("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<T extends string>(id: LiteralString<T>): HubSpotRef {
+  return createRef<"hubspot", HubSpotClient, T>("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<T extends string>(id: LiteralString<T>): IntercomRef {
+  return createRef<"intercom", IntercomClient, T>("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<T extends string>(id: LiteralString<T>): JiraRef {
+  return createRef<"jira", JiraClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): LaunchDarklyRef {
+  return createRef<"launchdarkly", LaunchDarklyClient, T>("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<T extends string>(id: LiteralString<T>): MistralRef {
+  return createRef<"mistral", MistralClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): PagerDutyRef {
+  return createRef<"pagerduty", PagerDutyClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): PerplexityRef {
+  return createRef<"perplexity", PerplexityClient, T>("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<T extends string>(id: LiteralString<T>): SegmentRef {
+  return createRef<"segment", SegmentClient, T>("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<T extends string>(id: LiteralString<T>): SendGridRef {
+  return createRef<"sendgrid", SendGridClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): StabilityAIRef {
+  return createRef<"stabilityai", StabilityAIClient, T>("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<T extends string>(id: LiteralString<T>): TwilioRef {
+  return createRef<"twilio", TwilioClient, T>("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<T extends string>(id: LiteralString<T>): ZendeskRef {
+  return createRef<"zendesk", ZendeskClient, T>("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<T extends string>(id: LiteralString<T>): ZoomRef {
+  return createRef<"zoom", ZoomClient, T>("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<T extends string>(id: LiteralString<T>): GraphQLRef {
+  return createRef<"graphqlintegration", GraphQLClient, T>(
+    "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<T extends string>(id: LiteralString<T>): MySQLRef {
+  return createRef<"mysql", MySQLClient, T>("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<T extends string>(id: LiteralString<T>): MariaDBRef {
+  return createRef<"mariadb", MariaDBClient, T>("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<T extends string>(id: LiteralString<T>): MSSQLRef {
+  return createRef<"mssql", MSSQLClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): CockroachDBRef {
+  return createRef<"cockroachdb", CockroachDBClient, T>("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<T extends string>(id: LiteralString<T>): OracleDBRef {
+  return createRef<"oracledb", OracleDBClient, T>("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<T extends string>(id: LiteralString<T>): RedshiftRef {
+  return createRef<"redshift", RedshiftClient, T>("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<T extends string>(id: LiteralString<T>): AthenaRef {
+  return createRef<"athena", AthenaClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): DatabricksRef {
+  return createRef<"databricks", DatabricksClient, T>("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<T extends string>(id: LiteralString<T>): BigQueryRef {
+  return createRef<"bigquery", BigQueryClient, T>("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<T extends string>(id: LiteralString<T>): MongoDBRef {
+  return createRef<"mongodb", MongoDBClient, T>("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<T extends string>(id: LiteralString<T>): DynamoDBRef {
+  return createRef<"dynamodb", DynamoDBClient, T>("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<T extends string>(id: LiteralString<T>): CosmosDBRef {
+  return createRef<"cosmosdb", CosmosDBClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): CouchbaseRef {
+  return createRef<"couchbase", CouchbaseClient, T>("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<T extends string>(id: LiteralString<T>): S3Ref {
+  return createRef<"s3", S3Client, T>("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<T extends string>(id: LiteralString<T>): GCSRef {
+  return createRef<"gcs", GCSClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): GoogleSheetsRef {
+  return createRef<"gsheets", GoogleSheetsClient, T>("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<T extends string>(id: LiteralString<T>): KafkaRef {
+  return createRef<"kafka", KafkaClient, T>("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<T extends string>(id: LiteralString<T>): KinesisRef {
+  return createRef<"kinesis", KinesisClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): SalesforceRef {
+  return createRef<"salesforce", SalesforceClient, T>("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<T extends string>(id: LiteralString<T>): RedisRef {
+  return createRef<"redis", RedisClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): SuperblocksOCRRef {
+  return createRef<"superblocks-ocr", SuperblocksOCRClient, T>(
+    "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<T extends string>(id: LiteralString<T>): PythonRef {
+  return createRef<"python", PythonClient, T>("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<T extends string>(
+  id: LiteralString<T>,
+): ConfluentRef {
+  return createRef<"confluent", KafkaClient, T>("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<T extends string>(id: LiteralString<T>): RedpandaRef {
+  return createRef<"redpanda", KafkaClient, T>("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<T extends string>(id: LiteralString<T>): LakebaseRef {
+  return createRef<"lakebase", LakebaseClient, T>("lakebase", id);
+}
+
+/**
+ * Declare a Snowflake Postgres integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function snowflakePostgres<T extends string>(
+  id: LiteralString<T>,
+): SnowflakePostgresRef {
+  return createRef<"snowflakepostgres", SnowflakePostgresClient, T>(
+    "snowflakepostgres",
+    id,
+  );
+}
+
+/**
+ * Declare an SMTP integration.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ */
+export function smtp<T extends string>(id: LiteralString<T>): SmtpRef {
+  return createRef<"smtp", SmtpClient, T>("smtp", id);
+}
+
+/**
+ * Declare a REST API Integration.
+ *
+ * Use this for REST API Integrations configured with a base URL and
+ * authentication in the integrations page.
+ *
+ * @param id - The integration ID (UUID)
+ * @returns An integration reference for use in the API config
+ *
+ * @example
+ * ```typescript
+ * import { api, z, restApiIntegration } from '@superblocksteam/sdk-api';
+ *
+ * const MY_API = 'a1b2c3d4-uuid';
+ *
+ * export default api({
+ *   integrations: {
+ *     myApi: restApiIntegration(MY_API),
+ *   },
+ *   output: z.object({ users: z.array(z.unknown()) }),
+ *   async run(ctx) {
+ *     const users = await ctx.integrations.myApi.apiRequest(
+ *       { method: 'GET', path: '/users' },
+ *       { response: z.object({ users: z.array(z.unknown()) }) },
+ *     );
+ *     return users;
+ *   },
+ * });
+ * ```
+ */
+export function restApiIntegration<T extends string>(
+  id: LiteralString<T>,
+): RestApiIntegrationRef {
+  return createRef<"restapiintegration", RestApiIntegrationPluginClient, T>(
+    "restapiintegration",
+    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>,
+  );
+}