@superblocksteam/sdk-api 2.0.178-next.2 → 2.0.179-next.0

package/README.md

@@ -62,6 +62,7 @@ import { api, z, postgres } from "@superblocksteam/sdk-api";
 
 const myApi = api({
   name: "GetUsers",
+  description: "Lists users from Postgres",
   integrations: { db: postgres("prod-postgres-id") },
   input: z.object({ limit: z.number() }),
   output: z.object({ users: z.array(z.object({ id: z.string() })) }),
@@ -243,6 +244,7 @@ const UserSchema = z.object({
 
 export default api({
   name: "GetUserById",
+  description: "Fetches one user by ID from Postgres",
 
   // Declare integrations upfront for type safety
   integrations: {
@@ -284,6 +286,7 @@ import { api, z } from "@superblocksteam/sdk-api";
 
 export const ListProfiles = api({
   name: "ListProfiles",
+  description: "Lists an organization's user profiles",
   input: z.object({ orgId: z.string() }),
   output: z.object({ profiles: z.array(z.object({ id: z.string() })) }),
   async run() {
@@ -293,6 +296,7 @@ export const ListProfiles = api({
 
 export const UpdateProfile = api({
   name: "UpdateProfile",
+  description: "Updates a user's profile",
   input: z.object({ userId: z.string() }),
   output: z.object({ ok: z.literal(true) }),
   async run() {
@@ -318,14 +322,14 @@ Defines a TypeScript-based API with input/output validation. Returns a complete
 
 #### Required Fields
 
-| Field          | Type                              | Description                                                                                                                                            |
-| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`         | `string`                          | **Required.** Unique identifier for the API                                                                                                            |
-| `description`  | `string`                          | Optional. Plain-language summary of what this API does and which integrations it uses. Auto-generated by the AI agent when creating or editing an API. |
-| `input`        | `z.ZodType`                       | **Required.** Zod schema for input validation                                                                                                          |
-| `output`       | `z.ZodType`                       | **Required.** Zod schema for output validation                                                                                                         |
-| `run`          | `(ctx, input) => Promise<Output>` | **Required.** The implementation function                                                                                                              |
-| `integrations` | `Record<string, IntegrationRef>`  | Optional. Integration declarations for the API                                                                                                         |
+| Field          | Type                              | Description                                                                                                                                                                                                                                                                                          |
+| -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                          | **Required.** Unique identifier for the API                                                                                                                                                                                                                                                          |
+| `description`  | `string`                          | Optional in the type, but always set it when creating or editing an API. A short plain-language phrase (under 10 words) on what the API does and which integrations it uses, such as "Fetches active orders from Postgres". Place it right after `name`, and update it when the API's logic changes. |
+| `input`        | `z.ZodType`                       | **Required.** Zod schema for input validation                                                                                                                                                                                                                                                        |
+| `output`       | `z.ZodType`                       | **Required.** Zod schema for output validation                                                                                                                                                                                                                                                       |
+| `run`          | `(ctx, input) => Promise<Output>` | **Required.** The implementation function                                                                                                                                                                                                                                                            |
+| `integrations` | `Record<string, IntegrationRef>`  | Optional. Integration declarations for the API                                                                                                                                                                                                                                                       |
 
 ### Context (`ctx`) and Input
 
@@ -354,6 +358,7 @@ const OPS_SLACK = "b2c3d4e5-6789-01ab-cdef-ghijklmnopqr";
 
 export default api({
   name: "ProcessUserWorkflow",
+  description: "Looks up a user in Postgres and notifies Slack",
   integrations: {
     db: postgres(PROD_POSTGRES),
     notifier: slack(OPS_SLACK),

package/dist/readme.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=readme.test.d.ts.map

package/dist/readme.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.test.d.ts","sourceRoot":"","sources":["../src/readme.test.ts"],"names":[],"mappings":""}

package/dist/readme.test.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+// getSdkApiDocs serves this README to the builder agent as its only guide to
+// writing APIs, so the agent copies what its examples and rules show.
+const README = readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "../README.md"), "utf8");
+/** The `api({ ... })` calls in the README's TypeScript code blocks. */
+function apiExamples() {
+    const blocks = [...README.matchAll(/```typescript\n([\s\S]*?)```/g)].map((match) => match[1]);
+    const examples = [];
+    for (const block of blocks) {
+        for (const call of block.matchAll(/\bapi\(\{\n([\s\S]*?)\n\}\);/g)) {
+            const body = call[1];
+            const name = /^\s*name: "([^"]+)",/m.exec(body)?.[1] ?? "(unnamed)";
+            examples.push({ name, body });
+        }
+    }
+    return examples;
+}
+describe("SDK API README", () => {
+    it("has api() examples to check", () => {
+        expect(apiExamples().length).toBeGreaterThanOrEqual(5);
+    });
+    it.each(apiExamples())("$name example sets a description right after its name", ({ body }) => {
+        const lines = body.split("\n").filter((line) => line.trim() !== "");
+        const nameIndex = lines.findIndex((line) => /^\s*name: /.test(line));
+        expect(nameIndex).toBeGreaterThanOrEqual(0);
+        expect(lines[nameIndex + 1]).toMatch(/^\s*description:\s*(".+"|$)/);
+    });
+    it("tells the agent to always set a description", () => {
+        const row = README.split("\n").find((line) => line.startsWith("| `description`"));
+        expect(row).toMatch(/always set it when creating or editing an API/i);
+    });
+});
+//# sourceMappingURL=readme.test.js.map

package/dist/readme.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.test.js","sourceRoot":"","sources":["../src/readme.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,6EAA6E;AAC7E,sEAAsE;AACtE,MAAM,MAAM,GAAG,YAAY,CACzB,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,CAAC,EAChE,MAAM,CACP,CAAC;AAEF,uEAAuE;AACvE,SAAS,WAAW;IAClB,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,+BAA+B,CAAC,CAAC,CAAC,GAAG,CACtE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CACpB,CAAC;IACF,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CACpB,uDAAuD,EACvD,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;QACX,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACpE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,MAAM,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC;IACtE,CAAC,CACF,CAAC;IAEF,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAC3C,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CACnC,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@superblocksteam/sdk-api",
-  "version": "2.0.178-next.2",
+  "version": "2.0.179-next.0",
   "description": "Superblocks SDK for TypeScript-based API definitions",
   "license": "Superblocks Community Software License",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superblocksteam/superblocks.git"
+  },
   "files": [
     "dist",
     "src",
@@ -22,7 +26,7 @@
   "devDependencies": {
     "@bufbuild/protobuf": "1.3.0",
     "@eslint/js": "^9.39.5",
-    "@superblocksteam/shared": "0.9620.3",
+    "@superblocksteam/shared": "0.9622.0",
     "@types/node": "^20.19.43",
     "@typescript/native": "npm:typescript@^7.0.2",
     "dotenv": "^16.6.1",

package/src/readme.test.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+// getSdkApiDocs serves this README to the builder agent as its only guide to
+// writing APIs, so the agent copies what its examples and rules show.
+const README = readFileSync(
+  resolve(dirname(fileURLToPath(import.meta.url)), "../README.md"),
+  "utf8",
+);
+
+/** The `api({ ... })` calls in the README's TypeScript code blocks. */
+function apiExamples(): { name: string; body: string }[] {
+  const blocks = [...README.matchAll(/```typescript\n([\s\S]*?)```/g)].map(
+    (match) => match[1],
+  );
+  const examples: { name: string; body: string }[] = [];
+  for (const block of blocks) {
+    for (const call of block.matchAll(/\bapi\(\{\n([\s\S]*?)\n\}\);/g)) {
+      const body = call[1];
+      const name = /^\s*name: "([^"]+)",/m.exec(body)?.[1] ?? "(unnamed)";
+      examples.push({ name, body });
+    }
+  }
+  return examples;
+}
+
+describe("SDK API README", () => {
+  it("has api() examples to check", () => {
+    expect(apiExamples().length).toBeGreaterThanOrEqual(5);
+  });
+
+  it.each(apiExamples())(
+    "$name example sets a description right after its name",
+    ({ body }) => {
+      const lines = body.split("\n").filter((line) => line.trim() !== "");
+      const nameIndex = lines.findIndex((line) => /^\s*name: /.test(line));
+      expect(nameIndex).toBeGreaterThanOrEqual(0);
+      expect(lines[nameIndex + 1]).toMatch(/^\s*description:\s*(".+"|$)/);
+    },
+  );
+
+  it("tells the agent to always set a description", () => {
+    const row = README.split("\n").find((line) =>
+      line.startsWith("| `description`"),
+    );
+    expect(row).toMatch(/always set it when creating or editing an API/i);
+  });
+});