@superblocksteam/sdk-api 0.0.4

package/dist/integrations/declarations.js

@@ -0,0 +1,753 @@
+/**
+ * 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 };
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Helper function to create an integration reference.
+ *
+ * @internal
+ */
+function createRef(pluginId, id) {
+    return { pluginId, id };
+}
+// -----------------------------------------------------------------------------
+// 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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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(id) {
+    return createRef("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(id) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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) {
+    return createRef("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(id) {
+    return createRef("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(id) {
+    return createRef("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(id) {
+    return createRef("restapiintegration", id);
+}
+/**
+ * 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) {
+    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) {
+    const integrations = api.integrations;
+    if (integrations === undefined || integrations === null) {
+        return [];
+    }
+    if (Array.isArray(integrations)) {
+        return integrations;
+    }
+    return extractIntegrationDeclarations(integrations);
+}
+//# sourceMappingURL=declarations.js.map