@superblocksteam/sdk 2.0.99 → 2.0.100-next.1

package/src/extract-api-integrations.mts

@@ -0,0 +1,345 @@
+import { parse } from "@babel/parser";
+
+export type IntegrationInfo = {
+  key: string;
+  pluginId: string;
+  id: string;
+};
+
+type AstNode = {
+  type?: string;
+  [key: string]: unknown;
+};
+
+function isNode(value: unknown): value is AstNode {
+  return !!value && typeof value === "object";
+}
+
+function getPropertyName(node: unknown): string | undefined {
+  if (!isNode(node)) {
+    return undefined;
+  }
+
+  if (node.type === "Identifier" && typeof node.name === "string") {
+    return node.name;
+  }
+
+  if (node.type === "StringLiteral" && typeof node.value === "string") {
+    return node.value;
+  }
+
+  return undefined;
+}
+
+function getLiteralString(node: unknown): string | undefined {
+  if (!isNode(node)) {
+    return undefined;
+  }
+
+  if (node.type === "StringLiteral" && typeof node.value === "string") {
+    return node.value;
+  }
+
+  if (
+    node.type === "TemplateLiteral" &&
+    Array.isArray(node.expressions) &&
+    node.expressions.length === 0 &&
+    Array.isArray(node.quasis) &&
+    node.quasis.length === 1
+  ) {
+    const quasi = node.quasis[0];
+    if (
+      isNode(quasi) &&
+      isNode(quasi.value) &&
+      typeof quasi.value.cooked === "string"
+    ) {
+      return quasi.value.cooked;
+    }
+  }
+
+  return undefined;
+}
+
+function getCalleeName(node: unknown): string | undefined {
+  if (!isNode(node)) {
+    return undefined;
+  }
+
+  if (node.type === "Identifier" && typeof node.name === "string") {
+    return node.name;
+  }
+
+  if (node.type === "MemberExpression") {
+    return getPropertyName(node.property);
+  }
+
+  return undefined;
+}
+
+function unwrapExpression(node: unknown): AstNode | undefined {
+  if (!isNode(node)) {
+    return undefined;
+  }
+
+  if (
+    node.type === "TSAsExpression" ||
+    node.type === "TSTypeAssertion" ||
+    node.type === "ParenthesizedExpression"
+  ) {
+    return unwrapExpression(node.expression);
+  }
+
+  return node;
+}
+
+function buildVariableInitializerMap(
+  programBody: unknown[],
+): Map<string, unknown> {
+  const initializers = new Map<string, unknown>();
+
+  for (const statement of programBody) {
+    if (
+      !isNode(statement) ||
+      statement.type !== "VariableDeclaration" ||
+      !Array.isArray(statement.declarations)
+    ) {
+      continue;
+    }
+
+    for (const declaration of statement.declarations) {
+      if (!isNode(declaration)) {
+        continue;
+      }
+
+      const identifier = declaration.id;
+      if (
+        !isNode(identifier) ||
+        identifier.type !== "Identifier" ||
+        typeof identifier.name !== "string"
+      ) {
+        continue;
+      }
+
+      initializers.set(identifier.name, declaration.init);
+    }
+  }
+
+  return initializers;
+}
+
+function resolveApiConfigObject(
+  expression: unknown,
+  variableInitializers: Map<string, unknown>,
+): AstNode | undefined {
+  const resolvedExpression = unwrapExpression(expression);
+  if (!resolvedExpression) {
+    return undefined;
+  }
+
+  if (
+    resolvedExpression.type === "Identifier" &&
+    typeof resolvedExpression.name === "string"
+  ) {
+    return resolveApiConfigObject(
+      variableInitializers.get(resolvedExpression.name),
+      variableInitializers,
+    );
+  }
+
+  if (
+    resolvedExpression.type !== "CallExpression" ||
+    getCalleeName(resolvedExpression.callee) !== "api" ||
+    !Array.isArray(resolvedExpression.arguments)
+  ) {
+    return undefined;
+  }
+
+  const config = unwrapExpression(resolvedExpression.arguments[0]);
+  if (!config || config.type !== "ObjectExpression") {
+    return undefined;
+  }
+
+  return config;
+}
+
+function findExportedApiConfigObject(
+  programBody: unknown[],
+): AstNode | undefined {
+  const variableInitializers = buildVariableInitializerMap(programBody);
+
+  for (const statement of programBody) {
+    if (!isNode(statement)) {
+      continue;
+    }
+
+    if (statement.type === "ExportDefaultDeclaration") {
+      return resolveApiConfigObject(
+        statement.declaration,
+        variableInitializers,
+      );
+    }
+
+    if (
+      statement.type === "ExportNamedDeclaration" &&
+      Array.isArray(statement.specifiers)
+    ) {
+      for (const specifier of statement.specifiers) {
+        if (
+          !isNode(specifier) ||
+          specifier.type !== "ExportSpecifier" ||
+          getPropertyName(specifier.exported) !== "default"
+        ) {
+          continue;
+        }
+
+        return resolveApiConfigObject(specifier.local, variableInitializers);
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function buildVariableReferenceMap(
+  programBody: unknown[],
+): Map<string, Omit<IntegrationInfo, "key">> {
+  const refs = new Map<string, Omit<IntegrationInfo, "key">>();
+
+  for (const statement of programBody) {
+    if (
+      !isNode(statement) ||
+      statement.type !== "VariableDeclaration" ||
+      !Array.isArray(statement.declarations)
+    ) {
+      continue;
+    }
+
+    for (const declaration of statement.declarations) {
+      if (!isNode(declaration)) {
+        continue;
+      }
+
+      const identifier = declaration.id;
+      const init = declaration.init;
+      if (
+        !isNode(identifier) ||
+        identifier.type !== "Identifier" ||
+        typeof identifier.name !== "string"
+      ) {
+        continue;
+      }
+
+      if (
+        !isNode(init) ||
+        init.type !== "CallExpression" ||
+        !Array.isArray(init.arguments)
+      ) {
+        continue;
+      }
+
+      const pluginId = getCalleeName(init.callee);
+      const id = getLiteralString(init.arguments[0]);
+      if (!pluginId || !id) {
+        continue;
+      }
+
+      refs.set(identifier.name, { pluginId, id });
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Extract integration declarations from an SDK API source file.
+ *
+ * Supports both inline declarations:
+ * `integrations: { db: postgres("uuid") }`
+ *
+ * and top-level variable references:
+ * `const DB = postgres("uuid"); integrations: { db: DB }`
+ */
+export function extractIntegrationsFromSource(
+  source: string,
+): IntegrationInfo[] {
+  let ast: ReturnType<typeof parse>;
+  try {
+    ast = parse(source, {
+      sourceType: "module",
+      plugins: ["typescript"],
+    });
+  } catch {
+    return [];
+  }
+
+  const variableRefs = buildVariableReferenceMap(ast.program.body);
+  const apiConfig = findExportedApiConfigObject(ast.program.body);
+  if (!apiConfig) {
+    return [];
+  }
+  const results: IntegrationInfo[] = [];
+
+  const apiConfigProperties = Array.isArray(apiConfig.properties)
+    ? apiConfig.properties
+    : [];
+  const integrationsProperty = apiConfigProperties.find(
+    (property: AstNode) =>
+      isNode(property) &&
+      property.type === "ObjectProperty" &&
+      getPropertyName(property.key) === "integrations",
+  );
+
+  if (
+    !isNode(integrationsProperty) ||
+    !isNode(integrationsProperty.value) ||
+    integrationsProperty.value.type !== "ObjectExpression"
+  ) {
+    return [];
+  }
+
+  const properties = Array.isArray(integrationsProperty.value.properties)
+    ? integrationsProperty.value.properties
+    : [];
+  for (const property of properties) {
+    if (!isNode(property) || property.type !== "ObjectProperty") {
+      continue;
+    }
+
+    const key = getPropertyName(property.key);
+    if (!key) {
+      continue;
+    }
+
+    if (
+      isNode(property.value) &&
+      property.value.type === "CallExpression" &&
+      Array.isArray(property.value.arguments)
+    ) {
+      const pluginId = getCalleeName(property.value.callee);
+      const id = getLiteralString(property.value.arguments[0]);
+      if (pluginId && id) {
+        results.push({ key, pluginId, id });
+      }
+      continue;
+    }
+
+    if (
+      isNode(property.value) &&
+      property.value.type === "Identifier" &&
+      typeof property.value.name === "string"
+    ) {
+      const resolved = variableRefs.get(property.value.name);
+      if (resolved) {
+        results.push({ key, ...resolved });
+      }
+    }
+  }
+
+  return results;
+}
+
+export function extractIntegrationIdsFromSource(source: string): string[] {
+  return extractIntegrationsFromSource(source).map(
+    (integration) => integration.id,
+  );
+}

package/src/extract-api-integrations.test.mts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import {
+  extractIntegrationIdsFromSource,
+  extractIntegrationsFromSource,
+} from "./extract-api-integrations.mjs";
+
+describe("extractIntegrationsFromSource", () => {
+  it("extracts integration declarations from API source", () => {
+    const source = `
+      import { api, postgres, slack } from "@superblocksteam/sdk-api";
+      export default api({
+        integrations: {
+          db: postgres("pg-uuid-prod"),
+          notifier: slack("slack-uuid"),
+        },
+      });
+    `;
+
+    expect(extractIntegrationsFromSource(source)).toEqual([
+      { key: "db", pluginId: "postgres", id: "pg-uuid-prod" },
+      { key: "notifier", pluginId: "slack", id: "slack-uuid" },
+    ]);
+  });
+
+  it("extracts declarations from top-level variable references", () => {
+    const source = `
+      import { api, postgres } from "@superblocksteam/sdk-api";
+      const DB = postgres("db-uuid");
+      export default api({
+        integrations: { myDb: DB },
+      });
+    `;
+
+    expect(extractIntegrationsFromSource(source)).toEqual([
+      { key: "myDb", pluginId: "postgres", id: "db-uuid" },
+    ]);
+  });
+
+  it("supports template literals without expressions", () => {
+    const source = `
+      import { api, postgres } from "@superblocksteam/sdk-api";
+      export default api({
+        integrations: { db: postgres(\`pg-uuid\`) },
+      });
+    `;
+
+    expect(extractIntegrationsFromSource(source)).toEqual([
+      { key: "db", pluginId: "postgres", id: "pg-uuid" },
+    ]);
+  });
+
+  it("ignores unrelated integrations objects outside the exported API config", () => {
+    const source = `
+      import { api, postgres, slack } from "@superblocksteam/sdk-api";
+
+      const helper = {
+        integrations: {
+          fake: postgres("11111111-1111-1111-1111-111111111111"),
+        },
+      };
+
+      const REAL = slack("22222222-2222-2222-2222-222222222222");
+
+      export default api({
+        integrations: { notifier: REAL },
+        async run() {
+          return helper.integrations.fake;
+        },
+      });
+    `;
+
+    expect(extractIntegrationsFromSource(source)).toEqual([
+      {
+        key: "notifier",
+        pluginId: "slack",
+        id: "22222222-2222-2222-2222-222222222222",
+      },
+    ]);
+  });
+
+  it("returns empty array when no integrations field is present", () => {
+    const source = `
+      import { api } from "@superblocksteam/sdk-api";
+      export default api({});
+    `;
+
+    expect(extractIntegrationsFromSource(source)).toEqual([]);
+  });
+
+  it("handles malformed source gracefully", () => {
+    expect(extractIntegrationsFromSource("this is not valid {{{ code")).toEqual(
+      [],
+    );
+  });
+});
+
+describe("extractIntegrationIdsFromSource", () => {
+  it("returns the extracted IDs in declaration order", () => {
+    const source = `
+      import { api, postgres, slack } from "@superblocksteam/sdk-api";
+      export default api({
+        integrations: {
+          db: postgres("pg-uuid-prod"),
+          notifier: slack("slack-uuid"),
+        },
+      });
+    `;
+
+    expect(extractIntegrationIdsFromSource(source)).toEqual([
+      "pg-uuid-prod",
+      "slack-uuid",
+    ]);
+  });
+});

package/src/sdk.test.ts

@@ -0,0 +1,106 @@
+import {
+  CommitType,
+  BillingPlan,
+  type GetApplicationCommitsResponseBody,
+  type GetPublicOrganizationSummaryResponseBody,
+} from "@superblocksteam/shared";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { fetchApplicationCommits, fetchOrganizationSummary } = vi.hoisted(
+  () => ({
+    fetchApplicationCommits: vi.fn(),
+    fetchOrganizationSummary: vi.fn(),
+  }),
+);
+
+vi.mock("./client.js", async () => {
+  const actual = await vi.importActual("./client.js");
+
+  return {
+    ...actual,
+    fetchApplicationCommits,
+    fetchOrganizationSummary,
+  };
+});
+
+import { SuperblocksSdk } from "./sdk.js";
+
+describe("SuperblocksSdk.fetchOrganizationSummary", () => {
+  beforeEach(() => {
+    fetchApplicationCommits.mockReset();
+    fetchOrganizationSummary.mockReset();
+  });
+
+  it("delegates to the client helper with the SDK context", async () => {
+    const expectedResponse: GetPublicOrganizationSummaryResponseBody = {
+      billing_plan: BillingPlan.ENTERPRISE,
+      name: "Customer Org",
+      organization_id: "org-123",
+      organization_type: "opa",
+      registered_opas: [
+        {
+          url: "https://opa.example.com",
+          version: "1.2.3",
+        },
+      ],
+    };
+    fetchOrganizationSummary.mockResolvedValue(expectedResponse);
+
+    const sdk = new SuperblocksSdk(
+      "test-token",
+      "https://staging.superblocks.com",
+      "1.2.3",
+    );
+
+    await expect(sdk.fetchOrganizationSummary("org-123")).resolves.toEqual(
+      expectedResponse,
+    );
+    expect(fetchOrganizationSummary).toHaveBeenCalledWith(
+      "1.2.3",
+      "test-token",
+      "https://staging.superblocks.com",
+      "org-123",
+    );
+  });
+});
+
+describe("SuperblocksSdk.fetchApplicationCommits", () => {
+  beforeEach(() => {
+    fetchApplicationCommits.mockReset();
+  });
+
+  it("delegates commit history requests with commit type filters", async () => {
+    const expectedResponse: GetApplicationCommitsResponseBody = {
+      autosaves: [],
+      commits: [],
+    };
+    fetchApplicationCommits.mockResolvedValue(expectedResponse);
+
+    const sdk = new SuperblocksSdk(
+      "test-token",
+      "https://staging.superblocks.com",
+      "1.2.3",
+    );
+
+    await expect(
+      sdk.fetchApplicationCommits({
+        applicationId: "app-123",
+        branch: "feature/test",
+        commitType: CommitType.ALL,
+        limit: 25,
+        offset: 50,
+      }),
+    ).resolves.toEqual(expectedResponse);
+    expect(fetchApplicationCommits).toHaveBeenCalledWith({
+      cliVersion: "1.2.3",
+      applicationId: "app-123",
+      branch: "feature/test",
+      commitType: CommitType.ALL,
+      token: "test-token",
+      superblocksBaseUrl: "https://staging.superblocks.com",
+      injectedHeaders: {},
+      limit: 25,
+      offset: 50,
+    });
+  });
+});

package/src/sdk.ts

@@ -1,4 +1,8 @@
-import { ExportViewMode } from "@superblocksteam/shared";
+import {
+  CommitType,
+  ExportViewMode,
+  type GetPublicOrganizationSummaryResponseBody,
+} from "@superblocksteam/shared";
 import {
   fetchApi,
   fetchApiCommits,
@@ -9,6 +13,7 @@ import {
   fetchApplications,
   fetchApplicationWithComponents,
   fetchCurrentUser,
+  fetchOrganizationSummary,
   getApplicationGitConfig,
   getGitFreshToken,
   sync,
@@ -23,6 +28,7 @@ import {
 } from "./client.js";
 import {
   downloadApplicationDirectory,
+  downloadDirectoryByHash,
   uploadLocalApplication,
   uploadLocalDirectory,
   printDirectoryEntries,
@@ -164,12 +170,14 @@ export class SuperblocksSdk {
   async fetchApplicationCommits({
     applicationId,
     branch,
+    commitType = CommitType.COMMIT,
     headers = {},
     limit,
     offset,
   }: {
     applicationId: string;
     branch: string;
+    commitType?: CommitType;
     headers?: Record<string, string>;
     limit?: number;
     offset?: number;
@@ -178,6 +186,7 @@ export class SuperblocksSdk {
       cliVersion: this.cliVersion,
       applicationId,
       branch,
+      commitType,
       token: this.token,
       superblocksBaseUrl: this.superblocksBaseUrl,
       injectedHeaders: headers,
@@ -310,6 +319,17 @@ export class SuperblocksSdk {
     );
   }
 
+  async fetchOrganizationSummary(
+    organizationId: string,
+  ): Promise<GetPublicOrganizationSummaryResponseBody> {
+    return fetchOrganizationSummary(
+      this.cliVersion,
+      this.token,
+      this.superblocksBaseUrl,
+      organizationId,
+    );
+  }
+
   async pushApplication({
     applicationId,
     applicationConfig,
@@ -405,6 +425,21 @@ export class SuperblocksSdk {
     );
   }
 
+  async dbfsGetDirectoryByHash({
+    hash,
+    localDirectoryPath,
+  }: {
+    hash: string;
+    localDirectoryPath: string;
+  }) {
+    await downloadDirectoryByHash(
+      this.token,
+      this.superblocksBaseUrl,
+      hash,
+      localDirectoryPath,
+    );
+  }
+
   async dbfsPutApplication({
     applicationId,
     branch,
@@ -438,10 +473,12 @@ export class SuperblocksSdk {
   async dbfsGetApplicationDirectoryHash({
     applicationId,
     branch,
+    commitId,
     silent,
   }: {
     applicationId: string;
-    branch: string | undefined;
+    branch?: string;
+    commitId?: string;
     silent?: boolean;
   }) {
     return getApplicationDirectoryHash(
@@ -449,7 +486,7 @@ export class SuperblocksSdk {
       this.superblocksBaseUrl,
       applicationId,
       branch,
-      { silent },
+      { commitId, silent },
     );
   }
 

package/src/telemetry/index.ts

@@ -18,8 +18,6 @@ import {
   resetTelemetry,
   getDefaultPolicy,
 } from "@superblocksteam/telemetry";
-// Note: dd-trace kept for LLMObs until Epic 07 completes
-import ddTrace from "dd-trace";
 import packageJson from "../../package.json" with { type: "json" };
 import {
   ATTR_SUPERBLOCKS_BASE_URL,
@@ -33,6 +31,7 @@ import { applyLocalObsEnvVars, isLocalObsEnabled } from "./local-obs.js";
 import { getLogger as getStandardLogger } from "./logging.js";
 import { getConfiguration, SERVICE_NAME } from "./util.js";
 import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/index.js";
+import type ddTraceDefault from "dd-trace";
 
 // Apply local observability env vars early, before dd-trace auto-init
 applyLocalObsEnvVars();
@@ -41,6 +40,17 @@ applyLocalObsEnvVars();
 let config: Awaited<ReturnType<typeof getConfiguration>> | undefined =
   undefined;
 let configured = false;
+type DdTrace = typeof ddTraceDefault;
+
+// Load dd-trace only when telemetry is explicitly configured. This keeps
+// lightweight SDK consumers from pulling in dd-trace as a module-load side
+// effect when they only need logger/tracer helpers.
+let ddTracePromise: Promise<DdTrace> | undefined = undefined;
+
+async function getDdTrace() {
+  ddTracePromise ??= import("dd-trace").then((module) => module.default);
+  return await ddTracePromise;
+}
 
 /**
  * Current deployment type based on SUPERBLOCKS_DEPLOYMENT_TYPE env var.
@@ -122,6 +132,7 @@ export async function configureTelemetry(
   // NOTE: @joeyagreco - we do this because (per DataDog support):
   // NOTE: @joeyagreco - "There is currently no way to define a retention filter directly for "LLM apps" unless those apps are associated with a specific service tag."
   const SERVICE_NAME_LLM = "superblocks-ai-code-gen";
+  const ddTrace = await getDdTrace();
   ddTrace.init({
     env: getEnvironmentFromHostname(config.superblocksHostname),
     service: SERVICE_NAME_LLM,