@fragno-dev/project-connector-fragment 0.0.0-stage → 0.0.1

package/dist/node/project-connector-client.js

@@ -0,0 +1,235 @@
+import { projectConnectorActionSchema, projectConnectorConnectionStateSchema, projectConnectorExecutionSchema, projectConnectorHttpUrlSchema, projectConnectorProfileSchema, projectConnectorProviderConfigsSchema } from "./project-connector-contracts.js";
+import { z } from "zod";
+import { Connector, ConnectorError, ProjectConnector } from "@oomol-lab/connector";
+//#region src/project-connector-client.ts
+const projectConnectorConnectionRequestSchema = z.object({
+	id: z.string().min(1),
+	projectId: z.string().min(1),
+	providerConfigId: z.string().min(1),
+	externalUserId: z.string().min(1),
+	service: z.string().min(1),
+	connectionName: z.string().nullable(),
+	authorizationUrl: projectConnectorHttpUrlSchema,
+	expiresAt: z.string()
+}).and(projectConnectorConnectionStateSchema);
+const projectConnectorCallOptions = { retries: 0 };
+const projectConnectorDiscoveryEnvelopeSchema = z.object({
+	success: z.literal(true),
+	data: projectConnectorProviderConfigsSchema.safeExtend({ providerConfigs: z.array(projectConnectorProviderConfigsSchema.shape.providerConfigs.element.extend({ actionIds: z.array(z.string().min(1)) })) })
+});
+const projectConnectorCatalogActionSchema = projectConnectorActionSchema.extend({ description: z.string().nullish().transform((description) => description ?? null) });
+function createOomolProjectConnectorSdk(config) {
+	return new ProjectConnector({
+		...config,
+		fetch: fetchProjectConnectorWithoutRedirects
+	});
+}
+/** A safe SDK failure exposes its code, never its raw response data or project API key. */
+var ProjectConnectorClientError = class extends Error {
+	code;
+	status;
+	constructor(code, status) {
+		super(`Project Connector request failed: ${code} (HTTP ${status})`);
+		this.code = code;
+		this.status = status;
+		this.name = "ProjectConnectorClientError";
+	}
+};
+function parseProjectConnectorApiBaseUrl(value) {
+	const baseUrl = new URL(projectConnectorHttpUrlSchema.parse(value));
+	const pathname = baseUrl.pathname.replace(/\/+$/, "");
+	if (baseUrl.search || baseUrl.hash || pathname !== "/v1") throw new Error("Project Connector baseUrl must be an origin followed by /v1");
+	baseUrl.pathname = pathname;
+	return baseUrl.toString().replace(/\/$/, "");
+}
+function parseProjectConnectorApiKey(value) {
+	return z.string().min(1).regex(/^[^\s]+$/).parse(value);
+}
+function projectConnectorClientErrorFromKnownFailure(error) {
+	if (error instanceof ProjectConnectorClientError) return error;
+	if (error instanceof ConnectorError) {
+		if (error.cause instanceof ProjectConnectorClientError) return error.cause;
+		console.warn("Project Connector gateway request failed", {
+			code: error.code,
+			status: error.status,
+			message: error.message,
+			requestId: error.requestId
+		});
+		return new ProjectConnectorClientError(error.code, error.status);
+	}
+	return null;
+}
+async function callProjectConnector(operation) {
+	try {
+		return await operation();
+	} catch (error) {
+		const knownFailure = projectConnectorClientErrorFromKnownFailure(error);
+		if (knownFailure) throw knownFailure;
+		throw error;
+	}
+}
+function parseProjectConnectorResponse(schema, value) {
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new ProjectConnectorClientError("invalid_response", 502);
+	return parsed.data;
+}
+async function fetchProjectConnectorWithoutRedirects(input, init) {
+	const response = await globalThis.fetch(input, {
+		...init,
+		redirect: "manual"
+	});
+	if ([
+		301,
+		302,
+		303,
+		307,
+		308
+	].includes(response.status)) {
+		await response.body?.cancel();
+		throw new ProjectConnectorClientError("unexpected_redirect", response.status);
+	}
+	return response;
+}
+async function fetchProjectConnectorProviderConfigs(config) {
+	const signal = AbortSignal.timeout(3e4);
+	let response;
+	try {
+		response = await fetchProjectConnectorWithoutRedirects(`${config.baseUrl}/saas/oauth/provider-configs`, {
+			method: "GET",
+			headers: { authorization: `Bearer ${config.apiKey}` },
+			signal
+		});
+	} catch (cause) {
+		if (signal.aborted) throw new ProjectConnectorClientError("client_timeout", 0);
+		if (cause instanceof TypeError) throw new ProjectConnectorClientError("client_network_error", 0);
+		throw cause;
+	}
+	let payload;
+	try {
+		payload = await response.json();
+	} catch (cause) {
+		if (signal.aborted) throw new ProjectConnectorClientError("client_timeout", 0);
+		if (cause instanceof TypeError) throw new ProjectConnectorClientError("client_network_error", 0);
+		if (!(cause instanceof SyntaxError)) throw cause;
+		payload = null;
+	}
+	const failure = z.object({ errorCode: z.string().min(1) }).safeParse(payload);
+	if (!response.ok || failure.success) throw new ProjectConnectorClientError(failure.success ? failure.data.errorCode : response.status === 429 ? "rate_limited" : "provider_error", response.status);
+	return parseProjectConnectorResponse(projectConnectorDiscoveryEnvelopeSchema, payload).data;
+}
+/** Project Connector adapter with retries disabled and project keys confined to server requests. */
+function createProjectConnectorClient(config, createSdk = createOomolProjectConnectorSdk) {
+	const apiKey = parseProjectConnectorApiKey(config.apiKey);
+	const baseUrl = parseProjectConnectorApiBaseUrl(config.baseUrl);
+	const client = createSdk({
+		apiKey,
+		baseUrl,
+		maxRetries: 0
+	});
+	const catalog = config.catalogApiKey === null ? null : new Connector({
+		apiKey: parseProjectConnectorApiKey(config.catalogApiKey),
+		baseUrl,
+		maxRetries: 0,
+		fetch: fetchProjectConnectorWithoutRedirects
+	}).catalog;
+	return {
+		async listProviderConfigs() {
+			const discovery = await fetchProjectConnectorProviderConfigs({
+				apiKey,
+				baseUrl
+			});
+			return {
+				projectId: discovery.projectId,
+				providerConfigs: discovery.providerConfigs.map((config) => ({
+					id: config.id,
+					service: config.service,
+					displayName: config.displayName,
+					callbackUrl: config.callbackUrl,
+					effectiveScopes: config.effectiveScopes,
+					proxyAvailable: config.proxyAvailable
+				}))
+			};
+		},
+		async listProviderActions(providerConfigId) {
+			const discovery = await fetchProjectConnectorProviderConfigs({
+				apiKey,
+				baseUrl
+			});
+			const config = discovery.providerConfigs.find((config) => config.id === providerConfigId);
+			if (!config) return null;
+			const actions = [];
+			if (config.actionIds.length > 0) {
+				if (!catalog) throw new ProjectConnectorClientError("catalog_not_configured", 503);
+				const serviceActions = parseProjectConnectorResponse(z.array(projectConnectorCatalogActionSchema).refine((actions) => new Set(actions.map((action) => action.id)).size === actions.length, "Catalog action IDs must be unique"), await callProjectConnector(() => catalog.actions(config.service, projectConnectorCallOptions)));
+				const actionsById = new Map(serviceActions.map((action) => [action.id, action]));
+				for (const actionId of new Set(config.actionIds)) {
+					const action = actionsById.get(actionId);
+					if (!action) throw new ProjectConnectorClientError("action_not_found", 502);
+					if (action.service !== config.service) throw new ProjectConnectorClientError("action_identity_mismatch", 502);
+					actions.push(action);
+				}
+			}
+			return {
+				projectId: discovery.projectId,
+				providerConfigId: config.id,
+				actions
+			};
+		},
+		async check() {
+			try {
+				await client.getConnectionRequest(`fragno-check-${crypto.randomUUID()}`, projectConnectorCallOptions);
+			} catch (error) {
+				const knownFailure = projectConnectorClientErrorFromKnownFailure(error);
+				if (knownFailure?.status === 404 && knownFailure.code === "connection_request_not_found") return { authenticated: true };
+				if (knownFailure) throw knownFailure;
+				throw error;
+			}
+			throw new ProjectConnectorClientError("unexpected_health_response", 502);
+		},
+		async connect(externalUserId, input) {
+			const request = await callProjectConnector(() => client.connect.oauth(externalUserId, {
+				..."providerConfigId" in input ? { providerConfigId: input.providerConfigId } : { service: input.service },
+				connectionName: input.connectionName,
+				returnUri: input.returnUri
+			}, projectConnectorCallOptions));
+			return parseProjectConnectorResponse(projectConnectorConnectionRequestSchema, request);
+		},
+		async getConnectionRequest(requestId) {
+			const request = await callProjectConnector(() => client.getConnectionRequest(requestId, projectConnectorCallOptions));
+			return parseProjectConnectorResponse(projectConnectorConnectionRequestSchema, request);
+		},
+		async getProfile(accountId) {
+			return parseProjectConnectorResponse(projectConnectorProfileSchema, await callProjectConnector(() => client.getUserProfile(accountId, projectConnectorCallOptions)));
+		},
+		async execute(account, actionId, input) {
+			const result = await callProjectConnector(() => client.executeRaw(account.externalUserId, actionId, input, {
+				providerConfigId: account.providerConfigId,
+				connectedAccountId: account.id,
+				retries: 0
+			}));
+			return parseProjectConnectorResponse(projectConnectorExecutionSchema, {
+				executionId: result.executionId,
+				actionId: result.actionId,
+				output: result.data
+			});
+		}
+	};
+}
+/** Pins the SDK response to the saved project, provider, user, and request identity. */
+function confirmProjectConnectorRequest(expected, actual) {
+	if (actual.id !== expected.id || actual.projectId !== expected.projectId || actual.providerConfigId !== expected.providerConfigId || actual.externalUserId !== expected.externalUserId || actual.service !== expected.service || actual.connectionName !== expected.connectionName) throw new ProjectConnectorClientError("connection_identity_mismatch", 502);
+	if (actual.status === "initiated" || actual.status === "expired") return { status: actual.status };
+	if (actual.status === "connected") return {
+		status: "connected",
+		connectedAccountId: actual.connectedAccountId
+	};
+	return {
+		status: "failed",
+		errorCode: actual.errorCode,
+		errorMessage: actual.errorMessage
+	};
+}
+//#endregion
+export { ProjectConnectorClientError, confirmProjectConnectorRequest, createProjectConnectorClient };
+
+//# sourceMappingURL=project-connector-client.js.map

package/dist/node/project-connector-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-connector-client.js","names":[],"sources":["../../src/project-connector-client.ts"],"sourcesContent":["import { z } from \"zod\";\n\nimport {\n  Connector,\n  ConnectorError,\n  ProjectConnector,\n  type ProjectApi,\n  type ProjectCallOptions,\n  type ProjectConnectorConfig,\n} from \"@oomol-lab/connector\";\n\nimport {\n  projectConnectorActionSchema,\n  projectConnectorConnectionStateSchema,\n  type projectConnectorConnectInputSchema,\n  projectConnectorExecutionSchema,\n  projectConnectorHttpUrlSchema,\n  projectConnectorProfileSchema,\n  projectConnectorProviderConfigsSchema,\n  type ProjectConnectorConnectionState,\n} from \"./project-connector-contracts\";\n\nconst projectConnectorConnectionRequestSchema = z\n  .object({\n    id: z.string().min(1),\n    projectId: z.string().min(1),\n    providerConfigId: z.string().min(1),\n    externalUserId: z.string().min(1),\n    service: z.string().min(1),\n    connectionName: z.string().nullable(),\n    authorizationUrl: projectConnectorHttpUrlSchema,\n    expiresAt: z.string(),\n  })\n  .and(projectConnectorConnectionStateSchema);\n\nconst projectConnectorCallOptions = { retries: 0 } satisfies ProjectCallOptions;\nconst projectConnectorDiscoveryEnvelopeSchema = z.object({\n  success: z.literal(true),\n  data: projectConnectorProviderConfigsSchema.safeExtend({\n    providerConfigs: z.array(\n      projectConnectorProviderConfigsSchema.shape.providerConfigs.element.extend({\n        actionIds: z.array(z.string().min(1)),\n      }),\n    ),\n  }),\n});\n\nconst projectConnectorCatalogActionSchema = projectConnectorActionSchema.extend({\n  description: z\n    .string()\n    .nullish()\n    .transform((description) => description ?? null),\n});\n\ntype ProjectConnectorSdk = Pick<\n  ProjectApi,\n  \"getConnectionRequest\" | \"getUserProfile\" | \"executeRaw\"\n> & {\n  readonly connect: Pick<ProjectApi[\"connect\"], \"oauth\">;\n};\n\ntype CreateProjectConnectorSdk = (config: ProjectConnectorConfig) => ProjectConnectorSdk;\n\nfunction createOomolProjectConnectorSdk(config: ProjectConnectorConfig): ProjectConnectorSdk {\n  return new ProjectConnector({\n    ...config,\n    // The wrapper also avoids the SDK calling native Workers fetch with a transport receiver.\n    fetch: fetchProjectConnectorWithoutRedirects,\n  });\n}\n\n/** A safe SDK failure exposes its code, never its raw response data or project API key. */\nexport class ProjectConnectorClientError extends Error {\n  constructor(\n    readonly code: string,\n    readonly status: number,\n  ) {\n    super(`Project Connector request failed: ${code} (HTTP ${status})`);\n    this.name = \"ProjectConnectorClientError\";\n  }\n}\n\n/** Server-only gateway credentials; null catalogApiKey disables action discovery, not account operations. */\nexport type ProjectConnectorClientConfig = {\n  baseUrl: string;\n  apiKey: string;\n  catalogApiKey: string | null;\n};\n\nfunction parseProjectConnectorApiBaseUrl(value: string): string {\n  const baseUrl = new URL(projectConnectorHttpUrlSchema.parse(value));\n  const pathname = baseUrl.pathname.replace(/\\/+$/, \"\");\n  if (baseUrl.search || baseUrl.hash || pathname !== \"/v1\") {\n    throw new Error(\"Project Connector baseUrl must be an origin followed by /v1\");\n  }\n  baseUrl.pathname = pathname;\n  return baseUrl.toString().replace(/\\/$/, \"\");\n}\n\nfunction parseProjectConnectorApiKey(value: string): string {\n  return z\n    .string()\n    .min(1)\n    .regex(/^[^\\s]+$/)\n    .parse(value);\n}\n\nfunction projectConnectorClientErrorFromKnownFailure(\n  error: unknown,\n): ProjectConnectorClientError | null {\n  if (error instanceof ProjectConnectorClientError) {\n    return error;\n  }\n  if (error instanceof ConnectorError) {\n    // The SDK wraps transport rejections as network errors; retain our safe redirect diagnosis.\n    if (error.cause instanceof ProjectConnectorClientError) {\n      return error.cause;\n    }\n    // Callers only see the code; the gateway's message (e.g. which input field it rejected) stays in\n    // server logs. Gateway messages never contain the project API key.\n    console.warn(\"Project Connector gateway request failed\", {\n      code: error.code,\n      status: error.status,\n      message: error.message,\n      requestId: error.requestId,\n    });\n    return new ProjectConnectorClientError(error.code, error.status);\n  }\n  return null;\n}\n\nasync function callProjectConnector<T>(operation: () => Promise<T>): Promise<T> {\n  try {\n    return await operation();\n  } catch (error) {\n    const knownFailure = projectConnectorClientErrorFromKnownFailure(error);\n    if (knownFailure) {\n      throw knownFailure;\n    }\n    throw error;\n  }\n}\n\nfunction parseProjectConnectorResponse<T>(schema: z.ZodType<T>, value: unknown): T {\n  const parsed = schema.safeParse(value);\n  if (!parsed.success) {\n    throw new ProjectConnectorClientError(\"invalid_response\", 502);\n  }\n  return parsed.data;\n}\n\nasync function fetchProjectConnectorWithoutRedirects(\n  input: RequestInfo | URL,\n  init: RequestInit | undefined,\n): Promise<Response> {\n  // Workers rejects redirect: \"error\" before sending the request. Manual mode keeps credentials\n  // on the original host; reject redirects before interpreting the response body.\n  const response = await globalThis.fetch(input, { ...init, redirect: \"manual\" });\n  if ([301, 302, 303, 307, 308].includes(response.status)) {\n    await response.body?.cancel();\n    throw new ProjectConnectorClientError(\"unexpected_redirect\", response.status);\n  }\n  return response;\n}\n\nasync function fetchProjectConnectorProviderConfigs(\n  config: Pick<ProjectConnectorClientConfig, \"baseUrl\" | \"apiKey\">,\n) {\n  // The SDK has no discovery method; redirects must not forward the project key elsewhere.\n  const signal = AbortSignal.timeout(30_000);\n  let response: Response;\n  try {\n    response = await fetchProjectConnectorWithoutRedirects(\n      `${config.baseUrl}/saas/oauth/provider-configs`,\n      {\n        method: \"GET\",\n        headers: { authorization: `Bearer ${config.apiKey}` },\n        signal,\n      },\n    );\n  } catch (cause) {\n    if (signal.aborted) {\n      throw new ProjectConnectorClientError(\"client_timeout\", 0);\n    }\n    if (cause instanceof TypeError) {\n      throw new ProjectConnectorClientError(\"client_network_error\", 0);\n    }\n    throw cause;\n  }\n  let payload: unknown;\n  try {\n    payload = await response.json();\n  } catch (cause) {\n    if (signal.aborted) {\n      throw new ProjectConnectorClientError(\"client_timeout\", 0);\n    }\n    if (cause instanceof TypeError) {\n      throw new ProjectConnectorClientError(\"client_network_error\", 0);\n    }\n    if (!(cause instanceof SyntaxError)) {\n      throw cause;\n    }\n    payload = null;\n  }\n  const failure = z.object({ errorCode: z.string().min(1) }).safeParse(payload);\n  if (!response.ok || failure.success) {\n    throw new ProjectConnectorClientError(\n      failure.success\n        ? failure.data.errorCode\n        : response.status === 429\n          ? \"rate_limited\"\n          : \"provider_error\",\n      response.status,\n    );\n  }\n  return parseProjectConnectorResponse(projectConnectorDiscoveryEnvelopeSchema, payload).data;\n}\n\n/** Project Connector adapter with retries disabled and project keys confined to server requests. */\nexport function createProjectConnectorClient(\n  config: ProjectConnectorClientConfig,\n  createSdk: CreateProjectConnectorSdk = createOomolProjectConnectorSdk,\n) {\n  const apiKey = parseProjectConnectorApiKey(config.apiKey);\n  const baseUrl = parseProjectConnectorApiBaseUrl(config.baseUrl);\n  const client = createSdk({ apiKey, baseUrl, maxRetries: 0 });\n  // Project credentials and catalog credentials have different authority; never substitute one for the other.\n  const catalog =\n    config.catalogApiKey === null\n      ? null\n      : new Connector({\n          apiKey: parseProjectConnectorApiKey(config.catalogApiKey),\n          baseUrl,\n          maxRetries: 0,\n          fetch: fetchProjectConnectorWithoutRedirects,\n        }).catalog;\n\n  return {\n    async listProviderConfigs() {\n      const discovery = await fetchProjectConnectorProviderConfigs({ apiKey, baseUrl });\n      return {\n        projectId: discovery.projectId,\n        providerConfigs: discovery.providerConfigs.map((config) => ({\n          id: config.id,\n          service: config.service,\n          displayName: config.displayName,\n          callbackUrl: config.callbackUrl,\n          effectiveScopes: config.effectiveScopes,\n          proxyAvailable: config.proxyAvailable,\n        })),\n      };\n    },\n    async listProviderActions(providerConfigId: string) {\n      const discovery = await fetchProjectConnectorProviderConfigs({ apiKey, baseUrl });\n      const config = discovery.providerConfigs.find((config) => config.id === providerConfigId);\n      if (!config) {\n        return null;\n      }\n      const actions: z.output<typeof projectConnectorActionSchema>[] = [];\n      if (config.actionIds.length > 0) {\n        if (!catalog) {\n          throw new ProjectConnectorClientError(\"catalog_not_configured\", 503);\n        }\n        const serviceActions = parseProjectConnectorResponse(\n          z\n            .array(projectConnectorCatalogActionSchema)\n            .refine(\n              (actions) => new Set(actions.map((action) => action.id)).size === actions.length,\n              \"Catalog action IDs must be unique\",\n            ),\n          await callProjectConnector(() =>\n            catalog.actions(config.service, projectConnectorCallOptions),\n          ),\n        );\n        const actionsById = new Map(serviceActions.map((action) => [action.id, action]));\n        // Fetching the service catalog never expands this configuration's allowlist.\n        for (const actionId of new Set(config.actionIds)) {\n          const action = actionsById.get(actionId);\n          if (!action) {\n            throw new ProjectConnectorClientError(\"action_not_found\", 502);\n          }\n          if (action.service !== config.service) {\n            throw new ProjectConnectorClientError(\"action_identity_mismatch\", 502);\n          }\n          actions.push(action);\n        }\n      }\n      return {\n        projectId: discovery.projectId,\n        providerConfigId: config.id,\n        actions,\n      };\n    },\n    async check() {\n      // The project API has no health endpoint. An authenticated lookup of a fresh,\n      // nonexistent request must return connection_request_not_found, not Unauthorized.\n      try {\n        await client.getConnectionRequest(\n          `fragno-check-${crypto.randomUUID()}`,\n          projectConnectorCallOptions,\n        );\n      } catch (error) {\n        const knownFailure = projectConnectorClientErrorFromKnownFailure(error);\n        if (knownFailure?.status === 404 && knownFailure.code === \"connection_request_not_found\") {\n          return { authenticated: true as const };\n        }\n        if (knownFailure) {\n          throw knownFailure;\n        }\n        throw error;\n      }\n      throw new ProjectConnectorClientError(\"unexpected_health_response\", 502);\n    },\n    async connect(\n      externalUserId: string,\n      input: z.infer<typeof projectConnectorConnectInputSchema>,\n    ) {\n      const request = await callProjectConnector(() =>\n        client.connect.oauth(\n          externalUserId,\n          {\n            ...(\"providerConfigId\" in input\n              ? { providerConfigId: input.providerConfigId }\n              : { service: input.service }),\n            connectionName: input.connectionName,\n            returnUri: input.returnUri,\n          },\n          projectConnectorCallOptions,\n        ),\n      );\n      return parseProjectConnectorResponse(projectConnectorConnectionRequestSchema, request);\n    },\n    async getConnectionRequest(requestId: string) {\n      const request = await callProjectConnector(() =>\n        client.getConnectionRequest(requestId, projectConnectorCallOptions),\n      );\n      return parseProjectConnectorResponse(projectConnectorConnectionRequestSchema, request);\n    },\n    async getProfile(accountId: string) {\n      const profile = await callProjectConnector(() =>\n        client.getUserProfile(accountId, projectConnectorCallOptions),\n      );\n      return parseProjectConnectorResponse(projectConnectorProfileSchema, profile);\n    },\n    async execute(\n      account: { externalUserId: string; providerConfigId: string; id: string },\n      actionId: string,\n      input: Record<string, unknown>,\n    ) {\n      const result = await callProjectConnector(() =>\n        client.executeRaw(account.externalUserId, actionId, input, {\n          providerConfigId: account.providerConfigId,\n          connectedAccountId: account.id,\n          retries: 0,\n        }),\n      );\n      return parseProjectConnectorResponse(projectConnectorExecutionSchema, {\n        executionId: result.executionId,\n        actionId: result.actionId,\n        output: result.data,\n      });\n    },\n  };\n}\n\n/** Pins the SDK response to the saved project, provider, user, and request identity. */\nexport function confirmProjectConnectorRequest(\n  expected: {\n    id: string;\n    projectId: string;\n    providerConfigId: string;\n    externalUserId: string;\n    service: string;\n    connectionName: string;\n  },\n  actual: Awaited<\n    ReturnType<ReturnType<typeof createProjectConnectorClient>[\"getConnectionRequest\"]>\n  >,\n): ProjectConnectorConnectionState {\n  if (\n    actual.id !== expected.id ||\n    actual.projectId !== expected.projectId ||\n    actual.providerConfigId !== expected.providerConfigId ||\n    actual.externalUserId !== expected.externalUserId ||\n    actual.service !== expected.service ||\n    actual.connectionName !== expected.connectionName\n  ) {\n    throw new ProjectConnectorClientError(\"connection_identity_mismatch\", 502);\n  }\n  if (actual.status === \"initiated\" || actual.status === \"expired\") {\n    return { status: actual.status };\n  }\n  if (actual.status === \"connected\") {\n    return { status: \"connected\", connectedAccountId: actual.connectedAccountId };\n  }\n  return { status: \"failed\", errorCode: actual.errorCode, errorMessage: actual.errorMessage };\n}\n"],"mappings":"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"}

package/dist/node/project-connector-contracts.d.ts

@@ -0,0 +1,179 @@
+import { z } from "zod";
+//#region src/project-connector-contracts.d.ts
+/** Only HTTP(S) URLs can be used as OAuth return destinations. */
+declare const projectConnectorHttpUrlSchema: z.ZodURL;
+/** A connection becomes usable only after the gateway confirms its account ID. */
+declare const projectConnectorConnectionStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  status: z.ZodLiteral<"initiated">;
+}, z.core.$strip>, z.ZodObject<{
+  status: z.ZodLiteral<"connected">;
+  connectedAccountId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  status: z.ZodLiteral<"failed">;
+  errorCode: z.ZodNullable<z.ZodString>;
+  errorMessage: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  status: z.ZodLiteral<"expired">;
+}, z.core.$strip>], "status">;
+/** Persisted connection lifecycle; provider credentials never enter this fragment. */
+type ProjectConnectorConnectionState = z.infer<typeof projectConnectorConnectionStateSchema>;
+/** Named selectors preserve exact source identity; user ownership comes only from authentication. */
+declare const projectConnectorNamedConnectionSchema: z.ZodObject<{
+  projectId: z.ZodString;
+  providerConfigId: z.ZodString;
+  connectionName: z.ZodString;
+}, z.core.$strict>;
+/** Select exactly one provider and name every connection explicitly. */
+declare const projectConnectorConnectInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+  service: z.ZodString;
+  connectionName: z.ZodString;
+  returnUri: z.ZodURL;
+}, z.core.$strict>, z.ZodObject<{
+  providerConfigId: z.ZodString;
+  connectionName: z.ZodString;
+  returnUri: z.ZodURL;
+}, z.core.$strict>]>;
+/** Public connection request projection, including its verified lifecycle. */
+declare const projectConnectorConnectionSchema: z.ZodObject<{
+  id: z.ZodString;
+  projectId: z.ZodString;
+  providerConfigId: z.ZodString;
+  externalUserId: z.ZodString;
+  service: z.ZodString;
+  connectionName: z.ZodString;
+  authorizationUrl: z.ZodURL;
+  expiresAt: z.ZodString;
+  state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"initiated">;
+  }, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"connected">;
+    connectedAccountId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"failed">;
+    errorCode: z.ZodNullable<z.ZodString>;
+    errorMessage: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>, z.ZodObject<{
+    status: z.ZodLiteral<"expired">;
+  }, z.core.$strip>], "status">;
+}, z.core.$strip>;
+/** Stored account selectors bind actions to a specific product user and provider. */
+declare const projectConnectorAccountSchema: z.ZodObject<{
+  id: z.ZodString;
+  projectId: z.ZodString;
+  providerConfigId: z.ZodString;
+  externalUserId: z.ZodString;
+  service: z.ZodString;
+  connectionName: z.ZodString;
+}, z.core.$strip>;
+/** Missing named requests remain JSON results rather than empty HTTP responses. */
+declare const projectConnectorNamedRequestSchema: z.ZodObject<{
+  request: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    providerConfigId: z.ZodString;
+    externalUserId: z.ZodString;
+    service: z.ZodString;
+    connectionName: z.ZodString;
+    authorizationUrl: z.ZodURL;
+    expiresAt: z.ZodString;
+    state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      status: z.ZodLiteral<"initiated">;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"connected">;
+      connectedAccountId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"failed">;
+      errorCode: z.ZodNullable<z.ZodString>;
+      errorMessage: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"expired">;
+    }, z.core.$strip>], "status">;
+  }, z.core.$strip>>;
+}, z.core.$strict>;
+/** Missing named accounts remain JSON results rather than empty HTTP responses. */
+declare const projectConnectorNamedAccountSchema: z.ZodObject<{
+  account: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    providerConfigId: z.ZodString;
+    externalUserId: z.ZodString;
+    service: z.ZodString;
+    connectionName: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strict>;
+/** Account pagination is owned by the fragment rather than the provider gateway. */
+declare const projectConnectorAccountsSchema: z.ZodObject<{
+  accounts: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    providerConfigId: z.ZodString;
+    externalUserId: z.ZodString;
+    service: z.ZodString;
+    connectionName: z.ZodString;
+  }, z.core.$strip>>;
+  cursor: z.ZodNullable<z.ZodString>;
+  hasNextPage: z.ZodBoolean;
+}, z.core.$strip>;
+/** Project-scoped OAuth provider overview excludes action IDs and credentials. */
+declare const projectConnectorProviderConfigsSchema: z.ZodObject<{
+  projectId: z.ZodString;
+  providerConfigs: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    service: z.ZodString;
+    displayName: z.ZodString;
+    callbackUrl: z.ZodURL;
+    effectiveScopes: z.ZodArray<z.ZodString>;
+    proxyAvailable: z.ZodBoolean;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Authoritative catalog contracts describe action values, not a provider's execution permissions. */
+declare const projectConnectorActionSchema: z.ZodObject<{
+  id: z.ZodString;
+  service: z.ZodString;
+  name: z.ZodString;
+  description: z.ZodNullable<z.ZodString>;
+  inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** Only actions allowed by this exact project OAuth configuration are included. */
+declare const projectConnectorProviderActionsSchema: z.ZodObject<{
+  projectId: z.ZodString;
+  providerConfigId: z.ZodString;
+  actions: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    service: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Project authentication does not imply that an individual provider account is usable. */
+declare const projectConnectorStatusSchema: z.ZodObject<{
+  authenticated: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** Read-only provider identity associated with one verified account. */
+declare const projectConnectorProfileSchema: z.ZodObject<{
+  connectedAccountId: z.ZodString;
+  externalUserId: z.ZodString;
+  service: z.ZodString;
+  profile: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodString;
+    username: z.ZodNullable<z.ZodString>;
+    displayName: z.ZodNullable<z.ZodString>;
+    avatarUrl: z.ZodNullable<z.ZodString>;
+    email: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  }, z.core.$strip>;
+  fetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+/** Action output stays opaque; execution IDs support upstream troubleshooting. */
+declare const projectConnectorExecutionSchema: z.ZodObject<{
+  executionId: z.ZodString;
+  actionId: z.ZodString;
+  output: z.ZodUnknown & z.ZodType<{} | null, unknown, z.core.$ZodTypeInternals<{} | null, unknown>>;
+}, z.core.$strip>;
+//#endregion
+export { ProjectConnectorConnectionState, projectConnectorAccountSchema, projectConnectorAccountsSchema, projectConnectorActionSchema, projectConnectorConnectInputSchema, projectConnectorConnectionSchema, projectConnectorConnectionStateSchema, projectConnectorExecutionSchema, projectConnectorHttpUrlSchema, projectConnectorNamedAccountSchema, projectConnectorNamedConnectionSchema, projectConnectorNamedRequestSchema, projectConnectorProfileSchema, projectConnectorProviderActionsSchema, projectConnectorProviderConfigsSchema, projectConnectorStatusSchema };
+//# sourceMappingURL=project-connector-contracts.d.ts.map

package/dist/node/project-connector-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-connector-contracts.d.ts","names":[],"sources":["../../src/project-connector-contracts.ts"],"mappings":";;;cAGa,+BAA6B,EAAA;;cAM7B,uCAAqC,EAAA,uBAAA,EAAA;;;;;;;;;;;;;KAYtC,kCAAkC,EAAE,aAAa;;cAYhD,uCAAqC,EAAA;;;;;;cAOrC,oCAAkC,EAAA,mBAAA,EAAA;;;;;;;;;;cAclC,kCAAgC,EAAA;;;;;;;;;;;;;;;;;;;;;;;cAahC,+BAA6B,EAAA;;;;;;;;;cAU7B,oCAAkC,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;cAKlC,oCAAkC,EAAA;;;;;;;;;;;cAKlC,gCAA8B,EAAA;;;;;;;;;;;;;cAO9B,uCAAqC,EAAA;;;;;;;;;;;;cAqBrC,8BAA4B,EAAA;;;;;;;;;cAU5B,uCAAqC,EAAA;;;;;;;;;;;;;cAOrC,8BAA4B,EAAA;;;;cAG5B,+BAA6B,EAAA;;;;;;;;;;;;;;;;cAiB7B,iCAA+B,EAAA"}

package/dist/node/project-connector-contracts.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+//#region src/project-connector-contracts.ts
+/** Only HTTP(S) URLs can be used as OAuth return destinations. */
+const projectConnectorHttpUrlSchema = z.url().refine((value) => {
+	const url = new URL(value);
+	return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password;
+}, "Expected an HTTP(S) URL without embedded credentials");
+/** A connection becomes usable only after the gateway confirms its account ID. */
+const projectConnectorConnectionStateSchema = z.discriminatedUnion("status", [
+	z.object({ status: z.literal("initiated") }),
+	z.object({
+		status: z.literal("connected"),
+		connectedAccountId: z.string().min(1)
+	}),
+	z.object({
+		status: z.literal("failed"),
+		errorCode: z.string().nullable(),
+		errorMessage: z.string().nullable()
+	}),
+	z.object({ status: z.literal("expired") })
+]);
+/** Mirrors the gateway's alias rule so invalid names fail here with a usable message. */
+const projectConnectorConnectionNameSchema = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "Connection names may only contain lowercase letters, digits, underscores, and hyphens, and must start with a letter or digit").describe("Lowercase letters, digits, underscores, and hyphens; starts with a letter or digit.");
+/** Named selectors preserve exact source identity; user ownership comes only from authentication. */
+const projectConnectorNamedConnectionSchema = z.strictObject({
+	projectId: z.string().min(1),
+	providerConfigId: z.string().min(1),
+	connectionName: projectConnectorConnectionNameSchema
+});
+/** Select exactly one provider and name every connection explicitly. */
+const projectConnectorConnectInputSchema = z.union([z.strictObject({
+	service: z.string().regex(/^[a-z0-9_-]+$/),
+	connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,
+	returnUri: projectConnectorHttpUrlSchema
+}), z.strictObject({
+	providerConfigId: projectConnectorNamedConnectionSchema.shape.providerConfigId,
+	connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,
+	returnUri: projectConnectorHttpUrlSchema
+})]);
+/** Public connection request projection, including its verified lifecycle. */
+const projectConnectorConnectionSchema = z.object({
+	id: z.string(),
+	projectId: z.string(),
+	providerConfigId: z.string(),
+	externalUserId: z.string(),
+	service: z.string(),
+	connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,
+	authorizationUrl: projectConnectorHttpUrlSchema,
+	expiresAt: z.string(),
+	state: projectConnectorConnectionStateSchema
+});
+/** Stored account selectors bind actions to a specific product user and provider. */
+const projectConnectorAccountSchema = z.object({
+	id: z.string(),
+	projectId: z.string(),
+	providerConfigId: z.string(),
+	externalUserId: z.string(),
+	service: z.string(),
+	connectionName: projectConnectorNamedConnectionSchema.shape.connectionName
+});
+/** Missing named requests remain JSON results rather than empty HTTP responses. */
+const projectConnectorNamedRequestSchema = z.strictObject({ request: projectConnectorConnectionSchema.nullable() });
+/** Missing named accounts remain JSON results rather than empty HTTP responses. */
+const projectConnectorNamedAccountSchema = z.strictObject({ account: projectConnectorAccountSchema.nullable() });
+/** Account pagination is owned by the fragment rather than the provider gateway. */
+const projectConnectorAccountsSchema = z.object({
+	accounts: z.array(projectConnectorAccountSchema),
+	cursor: z.string().nullable(),
+	hasNextPage: z.boolean()
+});
+/** Project-scoped OAuth provider overview excludes action IDs and credentials. */
+const projectConnectorProviderConfigsSchema = z.object({
+	projectId: z.string().min(1),
+	providerConfigs: z.array(z.object({
+		id: z.string().min(1),
+		service: z.string().min(1),
+		displayName: z.string(),
+		callbackUrl: projectConnectorHttpUrlSchema,
+		effectiveScopes: z.array(z.string().min(1)),
+		proxyAvailable: z.boolean()
+	}))
+}).refine(({ providerConfigs }) => new Set(providerConfigs.map((config) => config.id)).size === providerConfigs.length, "Provider configuration IDs must be unique");
+/** Authoritative catalog contracts describe action values, not a provider's execution permissions. */
+const projectConnectorActionSchema = z.object({
+	id: z.string().min(1),
+	service: z.string().min(1),
+	name: z.string(),
+	description: z.string().nullable(),
+	inputSchema: z.record(z.string(), z.unknown()),
+	outputSchema: z.record(z.string(), z.unknown())
+});
+/** Only actions allowed by this exact project OAuth configuration are included. */
+const projectConnectorProviderActionsSchema = z.object({
+	projectId: projectConnectorProviderConfigsSchema.shape.projectId,
+	providerConfigId: projectConnectorProviderConfigsSchema.shape.providerConfigs.element.shape.id,
+	actions: z.array(projectConnectorActionSchema)
+});
+/** Project authentication does not imply that an individual provider account is usable. */
+const projectConnectorStatusSchema = z.object({ authenticated: z.literal(true) });
+/** Read-only provider identity associated with one verified account. */
+const projectConnectorProfileSchema = z.object({
+	connectedAccountId: z.string(),
+	externalUserId: z.string(),
+	service: z.string(),
+	profile: z.object({
+		id: z.string(),
+		kind: z.string(),
+		username: z.string().nullable(),
+		displayName: z.string().nullable(),
+		avatarUrl: z.string().nullable(),
+		email: z.string().nullable(),
+		metadata: z.record(z.string(), z.unknown())
+	}),
+	fetchedAt: z.number()
+});
+/** Action output stays opaque; execution IDs support upstream troubleshooting. */
+const projectConnectorExecutionSchema = z.object({
+	executionId: z.string(),
+	actionId: z.string(),
+	output: z.unknown().refine((value) => value !== void 0, "Expected action output")
+});
+//#endregion
+export { projectConnectorAccountSchema, projectConnectorAccountsSchema, projectConnectorActionSchema, projectConnectorConnectInputSchema, projectConnectorConnectionSchema, projectConnectorConnectionStateSchema, projectConnectorExecutionSchema, projectConnectorHttpUrlSchema, projectConnectorNamedAccountSchema, projectConnectorNamedConnectionSchema, projectConnectorNamedRequestSchema, projectConnectorProfileSchema, projectConnectorProviderActionsSchema, projectConnectorProviderConfigsSchema, projectConnectorStatusSchema };
+
+//# sourceMappingURL=project-connector-contracts.js.map

package/dist/node/project-connector-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-connector-contracts.js","names":[],"sources":["../../src/project-connector-contracts.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** Only HTTP(S) URLs can be used as OAuth return destinations. */\nexport const projectConnectorHttpUrlSchema = z.url().refine((value) => {\n  const url = new URL(value);\n  return (url.protocol === \"https:\" || url.protocol === \"http:\") && !url.username && !url.password;\n}, \"Expected an HTTP(S) URL without embedded credentials\");\n\n/** A connection becomes usable only after the gateway confirms its account ID. */\nexport const projectConnectorConnectionStateSchema = z.discriminatedUnion(\"status\", [\n  z.object({ status: z.literal(\"initiated\") }),\n  z.object({ status: z.literal(\"connected\"), connectedAccountId: z.string().min(1) }),\n  z.object({\n    status: z.literal(\"failed\"),\n    errorCode: z.string().nullable(),\n    errorMessage: z.string().nullable(),\n  }),\n  z.object({ status: z.literal(\"expired\") }),\n]);\n\n/** Persisted connection lifecycle; provider credentials never enter this fragment. */\nexport type ProjectConnectorConnectionState = z.infer<typeof projectConnectorConnectionStateSchema>;\n\n/** Mirrors the gateway's alias rule so invalid names fail here with a usable message. */\nconst projectConnectorConnectionNameSchema = z\n  .string()\n  .regex(\n    /^[a-z0-9][a-z0-9_-]*$/,\n    \"Connection names may only contain lowercase letters, digits, underscores, and hyphens, and must start with a letter or digit\",\n  )\n  .describe(\"Lowercase letters, digits, underscores, and hyphens; starts with a letter or digit.\");\n\n/** Named selectors preserve exact source identity; user ownership comes only from authentication. */\nexport const projectConnectorNamedConnectionSchema = z.strictObject({\n  projectId: z.string().min(1),\n  providerConfigId: z.string().min(1),\n  connectionName: projectConnectorConnectionNameSchema,\n});\n\n/** Select exactly one provider and name every connection explicitly. */\nexport const projectConnectorConnectInputSchema = z.union([\n  z.strictObject({\n    service: z.string().regex(/^[a-z0-9_-]+$/),\n    connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,\n    returnUri: projectConnectorHttpUrlSchema,\n  }),\n  z.strictObject({\n    providerConfigId: projectConnectorNamedConnectionSchema.shape.providerConfigId,\n    connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,\n    returnUri: projectConnectorHttpUrlSchema,\n  }),\n]);\n\n/** Public connection request projection, including its verified lifecycle. */\nexport const projectConnectorConnectionSchema = z.object({\n  id: z.string(),\n  projectId: z.string(),\n  providerConfigId: z.string(),\n  externalUserId: z.string(),\n  service: z.string(),\n  connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,\n  authorizationUrl: projectConnectorHttpUrlSchema,\n  expiresAt: z.string(),\n  state: projectConnectorConnectionStateSchema,\n});\n\n/** Stored account selectors bind actions to a specific product user and provider. */\nexport const projectConnectorAccountSchema = z.object({\n  id: z.string(),\n  projectId: z.string(),\n  providerConfigId: z.string(),\n  externalUserId: z.string(),\n  service: z.string(),\n  connectionName: projectConnectorNamedConnectionSchema.shape.connectionName,\n});\n\n/** Missing named requests remain JSON results rather than empty HTTP responses. */\nexport const projectConnectorNamedRequestSchema = z.strictObject({\n  request: projectConnectorConnectionSchema.nullable(),\n});\n\n/** Missing named accounts remain JSON results rather than empty HTTP responses. */\nexport const projectConnectorNamedAccountSchema = z.strictObject({\n  account: projectConnectorAccountSchema.nullable(),\n});\n\n/** Account pagination is owned by the fragment rather than the provider gateway. */\nexport const projectConnectorAccountsSchema = z.object({\n  accounts: z.array(projectConnectorAccountSchema),\n  cursor: z.string().nullable(),\n  hasNextPage: z.boolean(),\n});\n\n/** Project-scoped OAuth provider overview excludes action IDs and credentials. */\nexport const projectConnectorProviderConfigsSchema = z\n  .object({\n    projectId: z.string().min(1),\n    providerConfigs: z.array(\n      z.object({\n        id: z.string().min(1),\n        service: z.string().min(1),\n        displayName: z.string(),\n        callbackUrl: projectConnectorHttpUrlSchema,\n        effectiveScopes: z.array(z.string().min(1)),\n        proxyAvailable: z.boolean(),\n      }),\n    ),\n  })\n  .refine(\n    ({ providerConfigs }) =>\n      new Set(providerConfigs.map((config) => config.id)).size === providerConfigs.length,\n    \"Provider configuration IDs must be unique\",\n  );\n\n/** Authoritative catalog contracts describe action values, not a provider's execution permissions. */\nexport const projectConnectorActionSchema = z.object({\n  id: z.string().min(1),\n  service: z.string().min(1),\n  name: z.string(),\n  description: z.string().nullable(),\n  inputSchema: z.record(z.string(), z.unknown()),\n  outputSchema: z.record(z.string(), z.unknown()),\n});\n\n/** Only actions allowed by this exact project OAuth configuration are included. */\nexport const projectConnectorProviderActionsSchema = z.object({\n  projectId: projectConnectorProviderConfigsSchema.shape.projectId,\n  providerConfigId: projectConnectorProviderConfigsSchema.shape.providerConfigs.element.shape.id,\n  actions: z.array(projectConnectorActionSchema),\n});\n\n/** Project authentication does not imply that an individual provider account is usable. */\nexport const projectConnectorStatusSchema = z.object({ authenticated: z.literal(true) });\n\n/** Read-only provider identity associated with one verified account. */\nexport const projectConnectorProfileSchema = z.object({\n  connectedAccountId: z.string(),\n  externalUserId: z.string(),\n  service: z.string(),\n  profile: z.object({\n    id: z.string(),\n    kind: z.string(),\n    username: z.string().nullable(),\n    displayName: z.string().nullable(),\n    avatarUrl: z.string().nullable(),\n    email: z.string().nullable(),\n    metadata: z.record(z.string(), z.unknown()),\n  }),\n  fetchedAt: z.number(),\n});\n\n/** Action output stays opaque; execution IDs support upstream troubleshooting. */\nexport const projectConnectorExecutionSchema = z.object({\n  executionId: z.string(),\n  actionId: z.string(),\n  output: z.unknown().refine((value) => value !== undefined, \"Expected action output\"),\n});\n"],"mappings":"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"}