@superblocksteam/sdk 2.0.99 → 2.0.100-next.0

package/src/client.ts

@@ -1,7 +1,12 @@
 import * as fs from "node:fs";
 import path from "node:path";
 import { Bucketeer, FileDescriptor } from "@superblocksteam/bucketeer-sdk";
-import { ExportViewMode } from "@superblocksteam/shared";
+import {
+  CommitType,
+  ExportViewMode,
+  type GetApplicationCommitsResponseBody,
+  type GetPublicOrganizationSummaryResponseBody,
+} from "@superblocksteam/shared";
 import {
   COMPONENT_EVENT_HEADER,
   ComponentEvent,
@@ -72,6 +77,7 @@ export interface ApplicationWrapper {
 
 export interface MultiPageApplicationWrapper {
   application: Record<string, any>;
+  deployedCommitId?: string | null;
   pages: Page[];
   apis: Record<string, any>[];
 }
@@ -116,25 +122,7 @@ type Branch = {
 
 type ResponseWithMeta<T> = { responseMeta: unknown; data: T };
 
-interface CommitDto {
-  commitMessage: string;
-  committer: {
-    name?: string;
-    email: string;
-  };
-  commitId: string;
-  commitDate: number;
-  branch?: string;
-  autosave?: boolean;
-  tag: string;
-  externalCommitId?: string | null;
-  externalCommitDate?: number | null;
-}
-
-export interface GetCommitsResponseBody {
-  autosaves: CommitDto[];
-  commits: CommitDto[];
-}
+export type GetCommitsResponseBody = GetApplicationCommitsResponseBody;
 
 enum ResourceType {
   APPLICATION = "APPLICATION",
@@ -959,6 +947,45 @@ export async function fetchCurrentUser(
   }
 }
 
+export async function fetchOrganizationSummary(
+  cliVersion: string,
+  token: string,
+  superblocksBaseUrl: string,
+  organizationId: string,
+): Promise<GetPublicOrganizationSummaryResponseBody> {
+  try {
+    const config: AxiosRequestConfig = {
+      method: "get",
+      url: new URL(
+        `${BASE_SERVER_PUBLIC_API_URL_v2}/organizations/${organizationId}/summary`,
+        superblocksBaseUrl,
+      ).toString(),
+      headers: {
+        Authorization: "Bearer " + token,
+        [CLI_VERSION_HEADER]: cliVersion,
+      },
+    };
+    const response = await axios(config);
+    return response.data.data as GetPublicOrganizationSummaryResponseBody;
+  } catch (e: any) {
+    if (axios.isAxiosError(e) && e.response?.status === 404) {
+      throw new NotFoundError(`Organization ${organizationId} was not found`);
+    }
+
+    let message: string;
+    if (e instanceof AxiosError) {
+      message =
+        (e.response?.data?.responseMeta?.message as string) ??
+        JSON.stringify(e.response?.data) ??
+        e.response?.statusText ??
+        e?.message;
+    } else {
+      message = `${e?.message ? e?.message : e}`;
+    }
+    throw new Error(`Could not fetch organization summary: ${message}`);
+  }
+}
+
 const createSocketConnectionIfNeeded = async (
   cliVersion: string,
   token: string,
@@ -1381,6 +1408,7 @@ export async function fetchApplicationCommits({
   cliVersion,
   applicationId,
   branch,
+  commitType = CommitType.COMMIT,
   token,
   superblocksBaseUrl,
   injectedHeaders = {},
@@ -1390,6 +1418,7 @@ export async function fetchApplicationCommits({
   cliVersion: string;
   applicationId: string;
   branch?: string;
+  commitType?: CommitType;
   token: string;
   superblocksBaseUrl: string;
   injectedHeaders: Record<string, string>;
@@ -1409,7 +1438,7 @@ export async function fetchApplicationCommits({
           superblocksBaseUrl,
         );
     serverURL.search = new URLSearchParams({
-      commitType: "commit",
+      commitType,
       ...(limit ? { limit: limit.toString() } : {}),
       ...(offset ? { offset: offset.toString() } : {}),
     }).toString();
@@ -1437,6 +1466,7 @@ export async function fetchApiCommits({
   cliVersion,
   applicationId,
   branch,
+  commitType = CommitType.COMMIT,
   token,
   superblocksBaseUrl,
   injectedHeaders = {},
@@ -1446,6 +1476,7 @@ export async function fetchApiCommits({
   cliVersion: string;
   applicationId: string;
   branch?: string;
+  commitType?: CommitType;
   token: string;
   superblocksBaseUrl: string;
   injectedHeaders: Record<string, string>;
@@ -1465,7 +1496,7 @@ export async function fetchApiCommits({
           superblocksBaseUrl,
         );
     serverURL.search = new URLSearchParams({
-      commitType: "commit",
+      commitType,
       ...(limit ? { limit: limit.toString() } : {}),
       ...(offset ? { offset: offset.toString() } : {}),
     }).toString();

package/src/collect-sdk-apis.mts

@@ -1,7 +1,16 @@
 import path from "node:path";
+import {
+  extractIntegrationsFromSource,
+  type IntegrationInfo,
+} from "./extract-api-integrations.mjs";
 import { parseSdkRegistry } from "./parse-sdk-registry.mjs";
 
-export type SdkApisResult = Record<string, { entryPoint: string }>;
+export type SdkApiEntry = {
+  entryPoint: string;
+  integrations?: IntegrationInfo[];
+};
+
+export type SdkApisResult = Record<string, SdkApiEntry>;
 
 export type CollectSdkApisFs = {
   pathExists: (p: string) => Promise<boolean>;
@@ -9,13 +18,14 @@ export type CollectSdkApisFs = {
 };
 
 /**
- * Collect SDK API entry points from the app's registry at server/apis/index.ts.
- * Keys match Object.keys(registry.default) so useApi("Key") works in both edit
- * and deployed modes.
+ * Collect SDK API entry points and declared integrations from the app's registry
+ * at server/apis/index.ts. Keys match Object.keys(registry.default) so
+ * useApi("Key") works in both edit and deployed modes.
  *
  * @param root - App root directory
  * @param fs - File system operations (pathExists, readFile)
- * @returns Map of API name → { entryPoint } or empty object if no registry
+ * @returns Map of API name → { entryPoint, integrations? } or empty object
+ * if no registry exists
  */
 export async function collectSdkApisFromRegistry(
   root: string,
@@ -37,7 +47,21 @@ export async function collectSdkApisFromRegistry(
 
   const sdkApis: SdkApisResult = {};
   for (const [apiName, entryPoint] of keyToPath) {
-    sdkApis[apiName] = { entryPoint };
+    const entry: SdkApiEntry = { entryPoint };
+    const absolutePath = path.join(root, entryPoint);
+
+    try {
+      const source = await fs.readFile(absolutePath, "utf-8");
+      const integrations = extractIntegrationsFromSource(source);
+      if (integrations.length > 0) {
+        entry.integrations = integrations;
+      }
+    } catch {
+      // Integration extraction is best-effort. If a source file cannot be read,
+      // still emit the entry point so SDK execution continues to work.
+    }
+
+    sdkApis[apiName] = entry;
   }
   return sdkApis;
 }

package/src/collect-sdk-apis.test.mts

@@ -44,13 +44,30 @@ import CreateOrder from './CreateOrder/api.js';
 const apis = { GetUsers, CreateOrder } as const;
 export default apis;
 `;
+    const readFile = vi.fn(async (filePath: string) => {
+      const rel = path.relative(root, filePath).replace(/\\/g, "/");
+      if (rel === "server/apis/index.ts") {
+        return registryContent;
+      }
+      if (rel === "server/apis/GetUsers/api.ts") {
+        return `export default api({ integrations: { db: postgres("pg-1") } });`;
+      }
+      if (rel === "server/apis/CreateOrder/api.ts") {
+        return `export default api({});`;
+      }
+      throw new Error(`Unexpected read: ${rel}`);
+    });
+
     const result = await collectSdkApisFromRegistry(root, {
       pathExists,
-      readFile: vi.fn().mockResolvedValue(registryContent),
+      readFile,
     });
 
     expect(result).toEqual({
-      GetUsers: { entryPoint: "server/apis/GetUsers/api.ts" },
+      GetUsers: {
+        entryPoint: "server/apis/GetUsers/api.ts",
+        integrations: [{ key: "db", pluginId: "postgres", id: "pg-1" }],
+      },
       CreateOrder: { entryPoint: "server/apis/CreateOrder/api.ts" },
     });
   });
@@ -61,13 +78,50 @@ import GetUsers from './v2/GetUsers/api.js';
 const apis = { GetUsers } as const;
 export default apis;
 `;
+    const readFile = vi.fn(async (filePath: string) => {
+      const rel = path.relative(root, filePath).replace(/\\/g, "/");
+      if (rel === "server/apis/index.ts") {
+        return registryContent;
+      }
+      if (rel === "server/apis/v2/GetUsers/api.ts") {
+        return `const DB = postgres("pg-2"); export default api({ integrations: { db: DB } });`;
+      }
+      throw new Error(`Unexpected read: ${rel}`);
+    });
+
+    const result = await collectSdkApisFromRegistry(root, {
+      pathExists,
+      readFile,
+    });
+
+    expect(result).toEqual({
+      GetUsers: {
+        entryPoint: "server/apis/v2/GetUsers/api.ts",
+        integrations: [{ key: "db", pluginId: "postgres", id: "pg-2" }],
+      },
+    });
+  });
+
+  it("keeps entryPoint when integration extraction fails", async () => {
+    const registryContent = `
+import GetUsers from './GetUsers/api.js';
+export default { GetUsers };
+`;
+    const readFile = vi.fn(async (filePath: string) => {
+      const rel = path.relative(root, filePath).replace(/\\/g, "/");
+      if (rel === "server/apis/index.ts") {
+        return registryContent;
+      }
+      throw new Error("source unreadable");
+    });
+
     const result = await collectSdkApisFromRegistry(root, {
       pathExists,
-      readFile: vi.fn().mockResolvedValue(registryContent),
+      readFile,
     });
 
     expect(result).toEqual({
-      GetUsers: { entryPoint: "server/apis/v2/GetUsers/api.ts" },
+      GetUsers: { entryPoint: "server/apis/GetUsers/api.ts" },
     });
   });
 

package/src/dbfs/client.test.ts

@@ -0,0 +1,116 @@
+import { ExportViewMode, NotFoundError } from "@superblocksteam/shared";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { connectToISocketRPCServer, unwrapResponseDto, warn } = vi.hoisted(
+  () => ({
+    connectToISocketRPCServer: vi.fn(),
+    unwrapResponseDto: vi.fn(),
+    warn: vi.fn(),
+  }),
+);
+
+vi.mock("../socket/index.js", () => ({
+  connectToISocketRPCServer,
+}));
+
+vi.mock("../telemetry/logging.js", () => ({
+  getLogger: () => ({
+    warn,
+  }),
+}));
+
+vi.mock("@superblocksteam/shared", async () => {
+  const actual = await vi.importActual("@superblocksteam/shared");
+
+  return {
+    ...actual,
+    unwrapResponseDto,
+  };
+});
+
+import { getApplicationDirectoryHash } from "./client.js";
+
+describe("getApplicationDirectoryHash", () => {
+  const directoryContentsGet = vi.fn();
+  const rpcClient = {
+    call: {
+      v3: {
+        application: {
+          directoryContents: {
+            get: directoryContentsGet,
+          },
+        },
+      },
+    },
+    close: vi.fn(),
+  };
+
+  beforeEach(() => {
+    connectToISocketRPCServer.mockReset();
+    directoryContentsGet.mockReset();
+    rpcClient.close.mockReset();
+    unwrapResponseDto.mockReset();
+    warn.mockReset();
+
+    connectToISocketRPCServer.mockResolvedValue(rpcClient);
+  });
+
+  it("does not fall back to the live hash for commit lookups", async () => {
+    directoryContentsGet.mockResolvedValue("commit-request");
+    unwrapResponseDto.mockRejectedValueOnce(
+      new NotFoundError("commit hash not found"),
+    );
+
+    await expect(
+      getApplicationDirectoryHash(
+        "token",
+        "https://app.superblocks.com",
+        "app-123",
+        "main",
+        { commitId: "commit-123" },
+      ),
+    ).rejects.toBeInstanceOf(NotFoundError);
+
+    expect(directoryContentsGet).toHaveBeenCalledTimes(1);
+    expect(directoryContentsGet).toHaveBeenCalledWith({
+      applicationId: "app-123",
+      commitId: "commit-123",
+      viewMode: ExportViewMode.EXPORT_COMMIT,
+    });
+    expect(warn).not.toHaveBeenCalled();
+    expect(rpcClient.close).toHaveBeenCalledOnce();
+  });
+
+  it("falls back from draft to live for non-commit lookups", async () => {
+    directoryContentsGet
+      .mockResolvedValueOnce("draft-request")
+      .mockResolvedValueOnce("live-request");
+    unwrapResponseDto
+      .mockRejectedValueOnce(new NotFoundError("draft hash not found"))
+      .mockResolvedValueOnce({ hash: "live-hash" });
+
+    await expect(
+      getApplicationDirectoryHash(
+        "token",
+        "https://app.superblocks.com",
+        "app-123",
+        "main",
+      ),
+    ).resolves.toBe("live-hash");
+
+    expect(directoryContentsGet).toHaveBeenNthCalledWith(1, {
+      applicationId: "app-123",
+      branchName: "main",
+      viewMode: ExportViewMode.EXPORT_DRAFT,
+    });
+    expect(directoryContentsGet).toHaveBeenNthCalledWith(2, {
+      applicationId: "app-123",
+      branchName: "main",
+      viewMode: ExportViewMode.EXPORT_LIVE,
+    });
+    expect(warn).toHaveBeenCalledWith(
+      "Draft state not found, using live edit hash: live-hash",
+    );
+    expect(rpcClient.close).toHaveBeenCalledOnce();
+  });
+});

package/src/dbfs/client.ts

@@ -15,44 +15,62 @@ export async function getApplicationDirectoryHash(
   superblocksBaseUrl: string,
   applicationId: string,
   branch: string | undefined,
-  options?: { silent?: boolean },
+  options?: { commitId?: string; silent?: boolean },
 ) {
   const rpcClient = await connectToISocketRPCServer({
     token,
     superblocksBaseUrl,
   });
   try {
-    const response = await unwrapResponseDto(
-      rpcClient.call.v3.application.directoryContents.get({
-        applicationId,
-        branchName: branch,
-        viewMode: ExportViewMode.EXPORT_DRAFT,
-      }),
-    );
-    const liveEditHash = response.hash;
-    if (!liveEditHash) {
-      throw new Error(
-        `No directory contents hash found for the view mode ${ExportViewMode.EXPORT_DRAFT}`,
+    if (options?.commitId) {
+      const response = await unwrapResponseDto(
+        rpcClient.call.v3.application.directoryContents.get({
+          applicationId,
+          commitId: options.commitId,
+          viewMode: ExportViewMode.EXPORT_COMMIT,
+        }),
       );
+      const commitHash = response.hash;
+      if (!commitHash) {
+        throw new Error(
+          `No directory contents hash found for commit ${options.commitId}`,
+        );
+      }
+      return commitHash;
     }
-    return liveEditHash;
-  } catch (e) {
-    if (e instanceof NotFoundError) {
+    try {
       const response = await unwrapResponseDto(
         rpcClient.call.v3.application.directoryContents.get({
           applicationId,
           branchName: branch,
-          viewMode: ExportViewMode.EXPORT_LIVE,
+          viewMode: ExportViewMode.EXPORT_DRAFT,
         }),
       );
-      if (!options?.silent) {
-        getLogger().warn(
-          `Draft state not found, using live edit hash: ${response.hash}`,
+      const liveEditHash = response.hash;
+      if (!liveEditHash) {
+        throw new Error(
+          `No directory contents hash found for the view mode ${ExportViewMode.EXPORT_DRAFT}`,
         );
       }
-      return response.hash;
+      return liveEditHash;
+    } catch (e) {
+      if (e instanceof NotFoundError) {
+        const response = await unwrapResponseDto(
+          rpcClient.call.v3.application.directoryContents.get({
+            applicationId,
+            branchName: branch,
+            viewMode: ExportViewMode.EXPORT_LIVE,
+          }),
+        );
+        if (!options?.silent) {
+          getLogger().warn(
+            `Draft state not found, using live edit hash: ${response.hash}`,
+          );
+        }
+        return response.hash;
+      }
+      throw e;
     }
-    throw e;
   } finally {
     rpcClient.close();
   }
@@ -86,6 +104,27 @@ export async function downloadApplicationDirectory(
   }
 }
 
+export async function downloadDirectoryByHash(
+  token: string,
+  superblocksBaseUrl: string,
+  directoryHash: string,
+  localDirectoryPath: string,
+): Promise<void> {
+  const rpcClient = await connectToISocketRPCServer({
+    token,
+    superblocksBaseUrl,
+  });
+  try {
+    await doDownloadDirectoryToLocal(
+      rpcClient,
+      directoryHash,
+      localDirectoryPath,
+    );
+  } finally {
+    rpcClient.close();
+  }
+}
+
 export async function uploadLocalApplication(
   token: string,
   superblocksBaseUrl: string,