@super_studio/ecforce-ai-agent-server 1.4.0-canary.1 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@super_studio/ecforce-ai-agent-server`
 
-ecforce AI Agent のサーバー向け SDK です。
+ecforce AIエージェント のサーバー向け SDK です。
 
 主に次の 2 つを提供します。
 
@@ -56,7 +56,7 @@ AI_AGENT_API_ENDPOINT=https://dev-agent.ec-force.com
 
 ### `spst()`
 
-Vercel AI SDK の `generateText()` / `streamText()` などから、ecforce AI Agent の proxy provider を使いたいときに使います。
+Vercel AI SDK の `generateText()` / `streamText()` などから、ecforce AIエージェント の proxy provider を使いたいときに使います。
 
 用途:
 
@@ -119,6 +119,47 @@ type AgentSession = {
 };
 ```
 
+### 外部アプリで利用規約の同意を管理する
+
+利用規約は `https://agent.ec-force.com/terms` で公開されています。外部アプリでは、このページへのリンクを表示してから同意を記録してください。
+
+DB に登録済みのユーザーは、Accounts API を呼ばずに同意状況だけ取得できます。
+
+```ts
+const terms = await client.internalTerms.status({
+  email: "user@example.com",
+  projectId: "project_123",
+});
+
+if (!terms.accepted) {
+  // 利用規約へのリンクと同意チェックボックスを表示
+}
+```
+
+ユーザーが同意したら、次の API で記録します。未登録ユーザーも同時に作成する場合だけ `createIfMissing: true` を指定してください。
+
+```ts
+await client.internalTerms.accept({
+  email: "user@example.com",
+  projectId: "project_123",
+  createIfMissing: true,
+});
+```
+
+ユーザー情報も必要な場合は `resolve` を使います。`createIfMissing` の既定値は `false` です。
+
+```ts
+const user = await client.internalUser.resolve({
+  email: "user@example.com",
+  projectId: "project_123",
+  createIfMissing: true,
+});
+
+console.log(user.role, user.plan, user.termsAcceptedAt);
+```
+
+存在しないユーザーに `createIfMissing: false` でアクセスすると、`NOT_FOUND` エラーになります。ユーザー作成時は既存のルールに従い、有料プロジェクトでは Accounts に登録済みのメールアドレスだけ作成できます。
+
 ### 内部 usage summary を取得する
 
 内部 API の利用例として、`/v1/internal/usage/summary` に対応する usage summary 取得は次のように呼べます。
@@ -266,6 +307,114 @@ const result = streamText({
 });
 ```
 
+### エラーハンドリング
+
+ユーザーが未登録、または利用規約に未同意の場合、プロキシは判別可能なエラーコードを返します。
+
+| HTTP | `error.code` | 意味 |
+| --- | --- | --- |
+| 404 | `user_not_found` | 指定したプロジェクトにユーザーが存在しない |
+| 403 | `terms_not_accepted` | ユーザーが利用規約に同意していない |
+
+```ts
+import { APICallError } from "ai";
+
+function isTermsNotAcceptedError(error: unknown) {
+  return (
+    APICallError.isInstance(error) &&
+    error.statusCode === 403 &&
+    error.responseBody?.includes("terms_not_accepted") === true
+  );
+}
+```
+
+クレジット上限に達すると、プロキシは **429** を返します。
+
+```json
+{
+  "error": {
+    "message": "Credit limit exceeded.",
+    "type": "rate_limit_error",
+    "code": "credit_limit_exceeded"
+  }
+}
+```
+
+Vercel AI SDK では、このエラーは `APICallError` として扱われます。`generateText` と `streamText` で受け取り方が異なる点に注意してください。
+
+#### `generateText`
+
+`generateText()` 自体が throw します。
+
+```ts
+import { APICallError, generateText } from "ai";
+import { createSpstProvider } from "@super_studio/ecforce-ai-agent-server/provider";
+
+const provider = createSpstProvider({ callerApp: "admin-dashboard" });
+
+try {
+  await generateText({
+    model: provider("openai/gpt-5.4"),
+    prompt: "売上の改善案を3つ提案して",
+    maxRetries: 0,
+    providerOptions: {
+      spst: {
+        projectId: "project_123",
+        email: "user@example.com",
+      },
+    },
+  });
+} catch (error) {
+  if (isCreditLimitError(error)) {
+    // 例: UI に「クレジット上限に達しました」を表示
+    return;
+  }
+
+  throw error;
+}
+
+function isCreditLimitError(error: unknown) {
+  return (
+    APICallError.isInstance(error) &&
+    error.statusCode === 429 &&
+    error.responseBody?.includes("credit_limit_exceeded") === true
+  );
+}
+```
+
+#### `streamText`
+
+`streamText()` の HTTP エラーは `onError` で受け取ります。`await result.text` 側で credit limit を判定する必要はありません。
+
+```ts
+import { APICallError, streamText } from "ai";
+import { createSpstProvider } from "@super_studio/ecforce-ai-agent-server/provider";
+
+const provider = createSpstProvider({ callerApp: "admin-dashboard" });
+
+const result = streamText({
+  model: provider("openai/gpt-5.4-mini"),
+  prompt: "FAQ の草案を作成して",
+  maxRetries: 0,
+  providerOptions: {
+    spst: {
+      projectId: "project_123",
+      email: "user@example.com",
+    },
+  },
+  onError: ({ error }) => {
+    if (isCreditLimitError(error)) {
+      // 例: UI に「クレジット上限に達しました」を表示
+      return;
+    }
+
+    console.error(error);
+  },
+});
+
+return result.toUIMessageStreamResponse();
+```
+
 ### Google Search tool を併用する
 
 Google 系モデルでは、AI SDK 側のツールを組み合わせて使えます。

package/dist/mcp-auth.d.cts

@@ -1,7 +1,7 @@
 //#region src/mcp-auth.d.ts
 /**
  * 共通のMCPトークンのペイロード。
- * すべてのapps(cdp, ma, bi)はこのトークンの形になります。
+ * すべてのapps(aidp, ma, bi)はこのトークンの形になります。
  */
 type MCPTokenPayload = {
   source: string;

package/dist/mcp-auth.d.mts

@@ -1,7 +1,7 @@
 //#region src/mcp-auth.d.ts
 /**
  * 共通のMCPトークンのペイロード。
- * すべてのapps(cdp, ma, bi)はこのトークンの形になります。
+ * すべてのapps(aidp, ma, bi)はこのトークンの形になります。
  */
 type MCPTokenPayload = {
   source: string;

package/dist/mcp-auth.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-auth.mjs","names":[],"sources":["../src/mcp-auth.ts"],"sourcesContent":["import { decode, encode } from \"./lib/jwt\";\n\n/**\n * 共通のMCPトークンのペイロード。\n * すべてのapps(cdp, ma, bi)はこのトークンの形になります。\n */\nexport type MCPTokenPayload = {\n  source: string;\n  user: {\n    id: string;\n    name: string;\n    email: string;\n    projectId: string;\n  };\n};\n\nconst DEFAULT_MAX_AGE = 60 * 10; // 10 minutes\nconst DEFAULT_SALT = process.env.STAGE === \"local\" ? \"dev\" : process.env.STAGE;\n\n/**\n * Uses Auth.js JWT encoding/decoding.\n * @see https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/jwt.ts\n */\nexport async function createMCPToken(\n  payload: MCPTokenPayload,\n  options?: {\n    secret?: string;\n    salt?: string;\n    maxAge?: number;\n  },\n) {\n  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;\n  const secret = options?.secret ?? process.env.MCP_TOKEN_SECRET;\n  const salt = options?.salt ?? DEFAULT_SALT;\n  if (!secret || !salt) {\n    throw new Error(\"Secret or salt is not set\");\n  }\n  const token = await encode<MCPTokenPayload>({\n    token: payload,\n    secret,\n    salt,\n    maxAge,\n  });\n  return {\n    token,\n    expiresAt: new Date(Date.now() + maxAge * 1000),\n  };\n}\n\n/**\n * Uses Auth.js JWT encoding/decoding.\n * @see https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/jwt.ts\n */\nexport async function decodeMCPToken(\n  token: string,\n  options?: {\n    secret?: string;\n    salt?: string;\n  },\n): Promise<MCPTokenPayload> {\n  const secret = options?.secret ?? process.env.MCP_TOKEN_SECRET;\n  const salt = options?.salt ?? DEFAULT_SALT;\n  if (!secret || !salt) {\n    throw new Error(\"Secret or salt is not set\");\n  }\n  const decoded = await decode<MCPTokenPayload>({\n    token,\n    secret,\n    salt,\n  });\n  if (!decoded) {\n    throw new Error(\"Invalid token\");\n  }\n  return decoded;\n}\n\nexport function getMcpToken(req: Request) {\n  const mcpToken = req.headers.get(\"X-MCP-Token\");\n  if (!mcpToken || typeof mcpToken !== \"string\") {\n    throw new Error(\"Unauthorized\");\n  }\n  return mcpToken;\n}\n"],"mappings":";;;AAgBA,MAAM,kBAAkB;AACxB,MAAM,eAAe,QAAQ,IAAI,UAAU,UAAU,QAAQ,QAAQ,IAAI;;;;;AAMzE,eAAsB,eACpB,SACA,SAKA;;CACA,MAAM,8EAAS,QAAS,mEAAU;CAClC,MAAM,8EAAS,QAAS,mEAAU,QAAQ,IAAI;CAC9C,MAAM,0EAAO,QAAS,6DAAQ;AAC9B,KAAI,CAAC,UAAU,CAAC,KACd,OAAM,IAAI,MAAM,4BAA4B;AAQ9C,QAAO;EACL,OAPY,MAAM,OAAwB;GAC1C,OAAO;GACP;GACA;GACA;GACD,CAAC;EAGA,WAAW,IAAI,KAAK,KAAK,KAAK,GAAG,SAAS,IAAK;EAChD;;;;;;AAOH,eAAsB,eACpB,OACA,SAI0B;;CAC1B,MAAM,+EAAS,QAAS,qEAAU,QAAQ,IAAI;CAC9C,MAAM,2EAAO,QAAS,+DAAQ;AAC9B,KAAI,CAAC,UAAU,CAAC,KACd,OAAM,IAAI,MAAM,4BAA4B;CAE9C,MAAM,UAAU,MAAM,OAAwB;EAC5C;EACA;EACA;EACD,CAAC;AACF,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,gBAAgB;AAElC,QAAO;;AAGT,SAAgB,YAAY,KAAc;CACxC,MAAM,WAAW,IAAI,QAAQ,IAAI,cAAc;AAC/C,KAAI,CAAC,YAAY,OAAO,aAAa,SACnC,OAAM,IAAI,MAAM,eAAe;AAEjC,QAAO"}
+{"version":3,"file":"mcp-auth.mjs","names":[],"sources":["../src/mcp-auth.ts"],"sourcesContent":["import { decode, encode } from \"./lib/jwt\";\n\n/**\n * 共通のMCPトークンのペイロード。\n * すべてのapps(aidp, ma, bi)はこのトークンの形になります。\n */\nexport type MCPTokenPayload = {\n  source: string;\n  user: {\n    id: string;\n    name: string;\n    email: string;\n    projectId: string;\n  };\n};\n\nconst DEFAULT_MAX_AGE = 60 * 10; // 10 minutes\nconst DEFAULT_SALT = process.env.STAGE === \"local\" ? \"dev\" : process.env.STAGE;\n\n/**\n * Uses Auth.js JWT encoding/decoding.\n * @see https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/jwt.ts\n */\nexport async function createMCPToken(\n  payload: MCPTokenPayload,\n  options?: {\n    secret?: string;\n    salt?: string;\n    maxAge?: number;\n  },\n) {\n  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;\n  const secret = options?.secret ?? process.env.MCP_TOKEN_SECRET;\n  const salt = options?.salt ?? DEFAULT_SALT;\n  if (!secret || !salt) {\n    throw new Error(\"Secret or salt is not set\");\n  }\n  const token = await encode<MCPTokenPayload>({\n    token: payload,\n    secret,\n    salt,\n    maxAge,\n  });\n  return {\n    token,\n    expiresAt: new Date(Date.now() + maxAge * 1000),\n  };\n}\n\n/**\n * Uses Auth.js JWT encoding/decoding.\n * @see https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/jwt.ts\n */\nexport async function decodeMCPToken(\n  token: string,\n  options?: {\n    secret?: string;\n    salt?: string;\n  },\n): Promise<MCPTokenPayload> {\n  const secret = options?.secret ?? process.env.MCP_TOKEN_SECRET;\n  const salt = options?.salt ?? DEFAULT_SALT;\n  if (!secret || !salt) {\n    throw new Error(\"Secret or salt is not set\");\n  }\n  const decoded = await decode<MCPTokenPayload>({\n    token,\n    secret,\n    salt,\n  });\n  if (!decoded) {\n    throw new Error(\"Invalid token\");\n  }\n  return decoded;\n}\n\nexport function getMcpToken(req: Request) {\n  const mcpToken = req.headers.get(\"X-MCP-Token\");\n  if (!mcpToken || typeof mcpToken !== \"string\") {\n    throw new Error(\"Unauthorized\");\n  }\n  return mcpToken;\n}\n"],"mappings":";;;AAgBA,MAAM,kBAAkB;AACxB,MAAM,eAAe,QAAQ,IAAI,UAAU,UAAU,QAAQ,QAAQ,IAAI;;;;;AAMzE,eAAsB,eACpB,SACA,SAKA;;CACA,MAAM,8EAAS,QAAS,mEAAU;CAClC,MAAM,8EAAS,QAAS,mEAAU,QAAQ,IAAI;CAC9C,MAAM,0EAAO,QAAS,6DAAQ;AAC9B,KAAI,CAAC,UAAU,CAAC,KACd,OAAM,IAAI,MAAM,4BAA4B;AAQ9C,QAAO;EACL,OAPY,MAAM,OAAwB;GAC1C,OAAO;GACP;GACA;GACA;GACD,CAAC;EAGA,WAAW,IAAI,KAAK,KAAK,KAAK,GAAG,SAAS,IAAK;EAChD;;;;;;AAOH,eAAsB,eACpB,OACA,SAI0B;;CAC1B,MAAM,+EAAS,QAAS,qEAAU,QAAQ,IAAI;CAC9C,MAAM,2EAAO,QAAS,+DAAQ;AAC9B,KAAI,CAAC,UAAU,CAAC,KACd,OAAM,IAAI,MAAM,4BAA4B;CAE9C,MAAM,UAAU,MAAM,OAAwB;EAC5C;EACA;EACA;EACD,CAAC;AACF,KAAI,CAAC,QACH,OAAM,IAAI,MAAM,gBAAgB;AAElC,QAAO;;AAGT,SAAgB,YAAY,KAAc;CACxC,MAAM,WAAW,IAAI,QAAQ,IAAI,cAAc;AAC/C,KAAI,CAAC,YAAY,OAAO,aAAa,SACnC,OAAM,IAAI,MAAM,eAAe;AAEjC,QAAO"}

package/dist/sdk/__generated__/index.cjs

@@ -262,13 +262,41 @@ var Api = class extends HttpClient {
 				format: "json"
 			}, params))
 		};
-		this.internalUser = { list2: (query, params = {}) => this.request(require_objectSpread2._objectSpread2({
-			path: `/v1/internal/user`,
-			method: "GET",
-			query,
-			secure: true,
-			format: "json"
-		}, params)) };
+		this.internalUser = {
+			list: (query, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/internal/user`,
+				method: "GET",
+				query,
+				secure: true,
+				format: "json"
+			}, params)),
+			resolve: (data, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/internal/user/resolve`,
+				method: "POST",
+				body: data,
+				secure: true,
+				type: ContentType.Json,
+				format: "json"
+			}, params))
+		};
+		this.internalTerms = {
+			status: (data, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/internal/terms/status`,
+				method: "POST",
+				body: data,
+				secure: true,
+				type: ContentType.Json,
+				format: "json"
+			}, params)),
+			accept: (data, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/internal/terms/accept`,
+				method: "POST",
+				body: data,
+				secure: true,
+				type: ContentType.Json,
+				format: "json"
+			}, params))
+		};
 		this.internalGlobalAgent = {
 			listGlobalAgents: (params = {}) => this.request(require_objectSpread2._objectSpread2({
 				path: `/v1/internal/global-agent`,
@@ -705,6 +733,29 @@ var Api = class extends HttpClient {
 				format: "json"
 			}, params))
 		};
+		this.mcpOauth = {
+			getGrants: (query, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/mcp-oauth/grants`,
+				method: "GET",
+				query,
+				secure: true,
+				format: "json"
+			}, params)),
+			postGrantsRevokeAll: (params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/mcp-oauth/grants/revoke-all`,
+				method: "POST",
+				secure: true,
+				format: "json"
+			}, params)),
+			"postGrants{id}Revoke": (id, data, params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/mcp-oauth/grants/${id}/revoke`,
+				method: "POST",
+				body: data,
+				secure: true,
+				type: ContentType.Json,
+				format: "json"
+			}, params))
+		};
 		this.savedPrompts = {
 			list: (params = {}) => this.request(require_objectSpread2._objectSpread2({
 				path: `/v1/saved-prompts`,
@@ -755,6 +806,12 @@ var Api = class extends HttpClient {
 				method: "POST",
 				secure: true,
 				format: "json"
+			}, params)),
+			createEmbedToken: (params = {}) => this.request(require_objectSpread2._objectSpread2({
+				path: `/v1/session/embed-token`,
+				method: "POST",
+				secure: true,
+				format: "json"
 			}, params))
 		};
 		this.usage = {