Merge pull request #1625 from tailor-platform/feat/aigateway-runtime

toiroakr · web-flow · commit cce97d8d97c7 · 2026-07-02T14:31:24.000+09:00
feat(sdk): add aigateway runtime wrapper with name registry narrowing
diff --git a/.changeset/aigateway-runtime-wrapper.md b/.changeset/aigateway-runtime-wrapper.md
@@ -0,0 +1,7 @@
+---
+"@tailor-platform/sdk": minor
+---
+
+Add a runtime wrapper for AI Gateway. Resolvers, executors, and workflow jobs can now resolve an AI Gateway's platform-assigned URL by name via `aigateway.get(name)` (imported from `@tailor-platform/sdk/runtime`), instead of using the raw `tailor.aigateway.get(...)` global. Use `mockAigateway()` from `@tailor-platform/sdk/vitest` to mock it in unit tests.
+
+The gateway name is type-checked and autocompleted against the AI Gateways defined via `defineAIGateway()`, once `tailor.d.ts` has been generated (via `tailor-sdk deploy`/`generate`), mirroring the existing `MachineUserNameRegistry`/`IdpNameRegistry`/`ConnectionNameRegistry` pattern.
diff --git a/packages/create-sdk/templates/executor/tailor.d.ts b/packages/create-sdk/templates/executor/tailor.d.ts
@@ -17,6 +17,7 @@ declare module "@tailor-platform/sdk" {
     "main-idp": true;
   }
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/generators/tailor.d.ts b/packages/create-sdk/templates/generators/tailor.d.ts
@@ -17,6 +17,7 @@ declare module "@tailor-platform/sdk" {
     "main-idp": true;
   }
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/hello-world/tailor.d.ts b/packages/create-sdk/templates/hello-world/tailor.d.ts
@@ -11,6 +11,7 @@ declare module "@tailor-platform/sdk" {
   interface MachineUserNameRegistry {}
   interface IdpNameRegistry {}
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/inventory-management/tailor.d.ts b/packages/create-sdk/templates/inventory-management/tailor.d.ts
@@ -16,6 +16,7 @@ declare module "@tailor-platform/sdk" {
   }
   interface IdpNameRegistry {}
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/resolver/tailor.d.ts b/packages/create-sdk/templates/resolver/tailor.d.ts
@@ -18,6 +18,7 @@ declare module "@tailor-platform/sdk" {
   }
   interface IdpNameRegistry {}
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/static-web-site/tailor.d.ts b/packages/create-sdk/templates/static-web-site/tailor.d.ts
@@ -17,6 +17,7 @@ declare module "@tailor-platform/sdk" {
     "my-idp": true;
   }
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/tailordb/tailor.d.ts b/packages/create-sdk/templates/tailordb/tailor.d.ts
@@ -16,6 +16,7 @@ declare module "@tailor-platform/sdk" {
   }
   interface IdpNameRegistry {}
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/create-sdk/templates/workflow/tailor.d.ts b/packages/create-sdk/templates/workflow/tailor.d.ts
@@ -15,6 +15,7 @@ declare module "@tailor-platform/sdk" {
   }
   interface IdpNameRegistry {}
   interface ConnectionNameRegistry {}
+  interface AIGatewayNameRegistry {}
 }
 
 export {};
diff --git a/packages/sdk/docs/runtime.md b/packages/sdk/docs/runtime.md
@@ -19,6 +19,7 @@ import {
   workflow,
   context,
   file,
+  aigateway,
 } from "@tailor-platform/sdk/runtime";
 
 const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
@@ -35,6 +36,8 @@ const executionId = await workflow.triggerWorkflow("approval", { reportId });
 const invoker = context.getInvoker();
 
 const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
+
+const { url } = await aigateway.get("my-aigateway");
 ```
 
 ## Subpath imports
@@ -79,6 +82,7 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `workflow` — workflow & job control (`triggerWorkflow`, `resumeWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`, `openDownloadStream` _(deprecated)_)
+- `aigateway` — AI Gateway URL resolution (`get`)
 
 ## Testing
 
diff --git a/packages/sdk/docs/services/aigateway.md b/packages/sdk/docs/services/aigateway.md
@@ -97,3 +97,17 @@ export default defineConfig({
   aiGateways: [aiGateway],
 });
 ```
+
+## Runtime Usage
+
+Resolvers, executors, and workflow jobs can resolve a gateway's platform-assigned URL by name via `aigateway.get()`. The name is type-checked and autocompleted against the AI Gateways defined in `aiGateways`:
+
+```typescript
+import { aigateway } from "@tailor-platform/sdk/runtime";
+
+const { url } = await aigateway.get("my-aigateway");
+
+// await aigateway.get("unknown"); // Type error — only "my-aigateway" is allowed
+```
+
+Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor-sdk generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.
diff --git a/packages/sdk/docs/testing.md b/packages/sdk/docs/testing.md
@@ -23,7 +23,7 @@ Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailo
 
 - `mockTailordb` — TailorDB query stubs and call recording
 - `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
-- `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv` — corresponding platform API mocks
+- `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway` — corresponding platform API mocks
 
 For tighter alignment with the production runtime — Node.js module blocking, Web-only globals, and platform API mocks — pair the resolver helpers with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below.
 
@@ -60,7 +60,7 @@ export default defineConfig({
 
 ### Acquiring mocks with `using`
 
-Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
+Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
 
 ```typescript
 import { mockTailordb } from "@tailor-platform/sdk/vitest";
@@ -302,6 +302,23 @@ test("mock encoding conversion", () => {
 });
 ```
 
+### AI Gateway Mock
+
+```typescript
+import { mockAigateway } from "@tailor-platform/sdk/vitest";
+
+test("resolves an AI Gateway URL", async () => {
+  using aigateway = mockAigateway();
+  aigateway.setUrls({ "my-aigateway": "https://my-aigateway.example.com" });
+
+  const { url } = await tailor.aigateway.get("my-aigateway");
+  expect(url).toBe("https://my-aigateway.example.com");
+  expect(aigateway.calls).toEqual([{ name: "my-aigateway" }]);
+});
+```
+
+Calling `get` for a name that hasn't been registered via `setUrls` throws.
+
 ### Loading Secrets from Config
 
 Pass a config path to load `defineSecretManager()` values into the mock:
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
@@ -136,6 +136,11 @@
       "types": "./dist/runtime/file.d.mts",
       "import": "./dist/runtime/file.mjs",
       "default": "./dist/runtime/file.mjs"
+    },
+    "./runtime/aigateway": {
+      "types": "./dist/runtime/aigateway.d.mts",
+      "import": "./dist/runtime/aigateway.mjs",
+      "default": "./dist/runtime/aigateway.mjs"
     }
   },
   "scripts": {
diff --git a/packages/sdk/scripts/build-entries.mjs b/packages/sdk/scripts/build-entries.mjs
@@ -23,4 +23,5 @@ export const entry = [
   "src/runtime/workflow.ts",
   "src/runtime/context.ts",
   "src/runtime/file.ts",
+  "src/runtime/aigateway.ts",
 ];
diff --git a/packages/sdk/src/cli/shared/type-generator.test.ts b/packages/sdk/src/cli/shared/type-generator.test.ts
@@ -135,6 +135,28 @@ describe("generateTypeDefinition", () => {
     expect(result).toContain('"google-oauth": true;');
     expect(result).toContain('"ms365-oauth": true;');
   });
+
+  test("should generate empty AIGatewayNameRegistry when no AI Gateways provided", () => {
+    const result = generateTypeDefinition(undefined, undefined);
+
+    expect(result).toContain("interface AIGatewayNameRegistry {}");
+  });
+
+  test("should generate AIGatewayNameRegistry with AI Gateway names", () => {
+    const result = generateTypeDefinition(
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      ["my-aigateway", "second-gateway"],
+    );
+
+    expect(result).toContain("interface AIGatewayNameRegistry");
+    expect(result).toContain('"my-aigateway": true;');
+    expect(result).toContain('"second-gateway": true;');
+  });
 });
 
 describe("resolveTypeDefinitionPath", () => {
@@ -292,4 +314,41 @@ describe("extractAttributesFromConfig + generateTypeDefinition", () => {
     expect(content).toContain('"google-oauth": true;');
     expect(content).toContain('"ms365-oauth": true;');
   });
+
+  test("extracts AI Gateway names into AIGatewayNameRegistry", () => {
+    const config = {
+      name: "test-app",
+      aiGateways: [{ name: "my-aigateway" } as never, { name: "second-gateway" } as never],
+    };
+
+    const { aiGatewayNames } = extractAttributesFromConfig(config);
+    expect(aiGatewayNames).toEqual(["my-aigateway", "second-gateway"]);
+
+    const content = generateTypeDefinition(
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      aiGatewayNames,
+    );
+    expect(content).toContain("interface AIGatewayNameRegistry");
+    expect(content).toContain('"my-aigateway": true;');
+    expect(content).toContain('"second-gateway": true;');
+  });
+
+  test("de-duplicates AI Gateway names so the registry has unique keys", () => {
+    const config = {
+      name: "test-app",
+      aiGateways: [
+        { name: "my-aigateway" } as never,
+        { name: "second-gateway" } as never,
+        { name: "my-aigateway" } as never,
+      ],
+    };
+
+    const { aiGatewayNames } = extractAttributesFromConfig(config);
+    expect(aiGatewayNames).toEqual(["my-aigateway", "second-gateway"]);
+  });
 });
diff --git a/packages/sdk/src/cli/shared/type-generator.ts b/packages/sdk/src/cli/shared/type-generator.ts
@@ -17,6 +17,7 @@ interface ExtractedAttributes {
   machineUserNames?: string[];
   idpNames?: string[];
   connectionNames?: string[];
+  aiGatewayNames?: string[];
 }
 
 type AttributeFieldLike = {
@@ -45,6 +46,7 @@ export function extractAttributesFromConfig(config: AppConfig): ExtractedAttribu
  * @param machineUserNames - Registered machine user names (used to narrow `authInvoker` strings)
  * @param idpNames - Registered IdP names (used to narrow `idpUser*Trigger({ idp })` strings)
  * @param connectionNames - Registered auth connection names (used to narrow `getConnectionToken()` strings)
+ * @param aiGatewayNames - Registered AI Gateway names (used to narrow `aigateway.get()` strings)
  * @returns Generated type definition source
  */
 export function generateTypeDefinition(
@@ -54,6 +56,7 @@ export function generateTypeDefinition(
   machineUserNames?: readonly string[],
   idpNames?: readonly string[],
   connectionNames?: readonly string[],
+  aiGatewayNames?: readonly string[],
 ): string {
   // Generate AttributeMap interface
   // attributeMap values are type string representations (e.g., "string", "boolean", "string[]")
@@ -140,6 +143,20 @@ ${idpNameFields}
 ${connectionNameFields}
   }`;
 
+  // Generate AIGatewayNameRegistry interface (same quoting rules as machine users).
+  const aiGatewayNameFields = aiGatewayNames?.length
+    ? aiGatewayNames
+        .map((name) => `    ${isValidIdentifier(name) ? name : JSON.stringify(name)}: true;`)
+        .join("\n")
+    : "";
+
+  const aiGatewayNameBody =
+    !aiGatewayNames || aiGatewayNames.length === 0
+      ? "{}"
+      : `{
+${aiGatewayNameFields}
+  }`;
+
   return ml /* ts */ `
 // This file is auto-generated by @tailor-platform/sdk
 // Do not edit this file manually
@@ -152,6 +169,7 @@ declare module "@tailor-platform/sdk" {
   interface MachineUserNameRegistry ${machineUserBody}
   interface IdpNameRegistry ${idpNameBody}
   interface ConnectionNameRegistry ${connectionNameBody}
+  interface AIGatewayNameRegistry ${aiGatewayNameBody}
 }
 
 export {};
@@ -164,9 +182,14 @@ function collectAttributesFromConfig(config: AppConfig): ExtractedAttributes {
   // `IdpNameRegistry` keys (which would be invalid TypeScript).
   const idpNames = config.idp?.length ? [...new Set(config.idp.map((idp) => idp.name))] : undefined;
 
+  // De-duplicate AI Gateway names for the same reason.
+  const aiGatewayNames = config.aiGateways?.length
+    ? [...new Set(config.aiGateways.map((gateway) => gateway.name))]
+    : undefined;
+
   const auth = config.auth;
   if (!auth || typeof auth !== "object") {
-    return idpNames ? { idpNames } : {};
+    return idpNames || aiGatewayNames ? { idpNames, aiGatewayNames } : {};
   }
 
   // Extract machine user names from auth.machineUsers (available regardless of userProfile vs. machineUserAttributes)
@@ -239,6 +262,7 @@ function collectAttributesFromConfig(config: AppConfig): ExtractedAttributes {
       machineUserNames,
       idpNames,
       connectionNames,
+      aiGatewayNames,
     };
   }
 
@@ -250,7 +274,7 @@ function collectAttributesFromConfig(config: AppConfig): ExtractedAttributes {
     ).machineUserAttributes;
 
     if (!machineUserAttributes) {
-      return { machineUserNames, idpNames, connectionNames };
+      return { machineUserNames, idpNames, connectionNames, aiGatewayNames };
     }
 
     const attributeMap = Object.entries(machineUserAttributes).reduce((acc, [key, field]) => {
@@ -263,10 +287,11 @@ function collectAttributesFromConfig(config: AppConfig): ExtractedAttributes {
       machineUserNames,
       idpNames,
       connectionNames,
+      aiGatewayNames,
     };
   }
 
-  return { machineUserNames, idpNames, connectionNames };
+  return { machineUserNames, idpNames, connectionNames, aiGatewayNames };
 }
 
 /**
@@ -304,8 +329,14 @@ interface GenerateUserTypesOptions {
 export async function generateUserTypes(options: GenerateUserTypesOptions): Promise<void> {
   const { config, configPath } = options;
   try {
-    const { attributeMap, attributeList, machineUserNames, idpNames, connectionNames } =
-      extractAttributesFromConfig(config);
+    const {
+      attributeMap,
+      attributeList,
+      machineUserNames,
+      idpNames,
+      connectionNames,
+      aiGatewayNames,
+    } = extractAttributesFromConfig(config);
     if (!attributeMap && !attributeList) {
       logger.info("No attributes found in configuration", { mode: "plain" });
     }
@@ -325,6 +356,9 @@ export async function generateUserTypes(options: GenerateUserTypesOptions): Prom
     if (connectionNames?.length) {
       logger.debug(`Extracted ConnectionNames: ${JSON.stringify(connectionNames)}`);
     }
+    if (aiGatewayNames?.length) {
+      logger.debug(`Extracted AIGatewayNames: ${JSON.stringify(aiGatewayNames)}`);
+    }
 
     const env = config.env;
     if (env) {
@@ -339,6 +373,7 @@ export async function generateUserTypes(options: GenerateUserTypesOptions): Prom
       machineUserNames,
       idpNames,
       connectionNames,
+      aiGatewayNames,
     );
     const outputPath = resolveTypeDefinitionPath(configPath);
 
diff --git a/packages/sdk/src/configure/index.ts b/packages/sdk/src/configure/index.ts
@@ -30,6 +30,7 @@ export {
   type ConnectionNameRegistry,
   type ConnectionName,
 } from "#/configure/types/connection-name";
+export { type AIGatewayNameRegistry, type AIGatewayName } from "#/configure/types/aigateway-name";
 
 export * from "#/configure/services/index";
 
diff --git a/packages/sdk/src/configure/types/aigateway-name.ts b/packages/sdk/src/configure/types/aigateway-name.ts
diff --git a/packages/sdk/src/runtime/aigateway.test.ts b/packages/sdk/src/runtime/aigateway.test.ts
diff --git a/packages/sdk/src/runtime/aigateway.ts b/packages/sdk/src/runtime/aigateway.ts
diff --git a/packages/sdk/src/runtime/index.ts b/packages/sdk/src/runtime/index.ts
diff --git a/packages/sdk/src/vitest/index.ts b/packages/sdk/src/vitest/index.ts
diff --git a/packages/sdk/src/vitest/mock.ts b/packages/sdk/src/vitest/mock.ts

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ declare module "@tailor-platform/sdk" {`
`17`	`17`	`"main-idp": true;`
`18`	`18`	`}`
`19`	`19`	`interface ConnectionNameRegistry {}`
	`20`	`+ interface AIGatewayNameRegistry {}`
`20`	`21`	`}`
`21`	`22`
`22`	`23`	`export {};`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@ declare module "@tailor-platform/sdk" {`
`11`	`11`	`interface MachineUserNameRegistry {}`
`12`	`12`	`interface IdpNameRegistry {}`
`13`	`13`	`interface ConnectionNameRegistry {}`
	`14`	`+ interface AIGatewayNameRegistry {}`
`14`	`15`	`}`
`15`	`16`
`16`	`17`	`export {};`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ declare module "@tailor-platform/sdk" {`
`16`	`16`	`}`
`17`	`17`	`interface IdpNameRegistry {}`
`18`	`18`	`interface ConnectionNameRegistry {}`
	`19`	`+ interface AIGatewayNameRegistry {}`
`19`	`20`	`}`
`20`	`21`
`21`	`22`	`export {};`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ declare module "@tailor-platform/sdk" {`
`18`	`18`	`}`
`19`	`19`	`interface IdpNameRegistry {}`
`20`	`20`	`interface ConnectionNameRegistry {}`
	`21`	`+ interface AIGatewayNameRegistry {}`
`21`	`22`	`}`
`22`	`23`
`23`	`24`	`export {};`
Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ declare module "@tailor-platform/sdk" {`
`15`	`15`	`}`
`16`	`16`	`interface IdpNameRegistry {}`
`17`	`17`	`interface ConnectionNameRegistry {}`
	`18`	`+ interface AIGatewayNameRegistry {}`
`18`	`19`	`}`
`19`	`20`
`20`	`21`	`export {};`