/**
 * 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.apiRequest(...);
 *     return { name: users[0].name };
 *   },
 * });
 * ```
 */

import type { AirtableClient } from "./airtable/index.js";
import type { AnthropicClient } from "./anthropic/index.js";
import type { AsanaClient } from "./asana/index.js";
import type { AthenaClient } from "./athena/index.js";
import type { BigQueryClient } from "./bigquery/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 { CockroachDBClient } from "./cockroachdb/index.js";
import type { CohereClient } from "./cohere/index.js";
import type { ConfluenceClient } from "./confluence/index.js";
import type { CosmosDBClient } from "./cosmosdb/index.js";
import type { DatabricksClient } from "./databricks/index.js";
import type { DatadogClient } from "./datadog/index.js";
import type { DropboxClient } from "./dropbox/index.js";
import type { DynamoDBClient } from "./dynamodb/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 { GCSClient } from "./gcs/index.js";
import type { GeminiClient } from "./gemini/index.js";
import type { GitHubClient } from "./github/index.js";
import type { GoogleAnalyticsClient } from "./googleanalytics/index.js";
import type { GoogleDriveClient } from "./googledrive/index.js";
import type { GraphQLClient } from "./graphql/index.js";
import type { GroqClient } from "./groq/index.js";
import type { GoogleSheetsClient } from "./gsheets/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 { LakebaseClient } from "./lakebase/index.js";
import type { LaunchDarklyClient } from "./launchdarkly/index.js";
import type { MariaDBClient } from "./mariadb/index.js";
import type { MistralClient } from "./mistral/index.js";
import type { MongoDBClient } from "./mongodb/index.js";
import type { MSSQLClient } from "./mssql/index.js";
import type { MySQLClient } from "./mysql/index.js";
import type { NotionClient } from "./notion/index.js";
import type { OpenAIClient } from "./openai_v2/index.js";
import type { OracleDBClient } from "./oracledb/index.js";
import type { PagerDutyClient } from "./pagerduty/index.js";
import type { PerplexityClient } from "./perplexity/index.js";
import type { PostgresClient } from "./postgres/index.js";
import type { RedshiftClient } from "./redshift/index.js";
import type { RestApiIntegrationPluginClient } from "./restapiintegration/index.js";
import type { S3Client } from "./s3/index.js";
import type { SalesforceClient } from "./salesforce/index.js";
import type { SegmentClient } from "./segment/index.js";
import type { SendGridClient } from "./sendgrid/index.js";
import type { SlackClient } from "./slack/index.js";
import type { SmtpClient } from "./smtp/index.js";
import type { SnowflakeClient } from "./snowflake/index.js";
import type { SnowflakeCortexClient } from "./snowflakecortex/index.js";
import type { SnowflakePostgresClient } from "./snowflakepostgres/index.js";
import type { StabilityAIClient } from "./stabilityai/index.js";
import type { StripeClient } from "./stripe/index.js";
import type { SuperblocksOCRClient } from "./superblocks-ocr/index.js";
import type { TwilioClient } from "./twilio/index.js";
import type { ZendeskClient } from "./zendesk/index.js";
import type { ZoomClient } from "./zoom/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 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 Salesforce integration */
export type SalesforceRef = IntegrationRef<"salesforce", SalesforceClient>;

/** Reference to a Superblocks OCR integration */
export type SuperblocksOCRRef = IntegrationRef<
  "superblocks-ocr",
  SuperblocksOCRClient
>;

/** 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.apiRequest(
 *       { method: 'POST', path: '/chat.postMessage', body: { channel: '#alerts', text: message } },
 *       { response: z.object({ ok: z.boolean() }) }
 *     );
 *     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 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 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 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 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>,
  );
}