@frockbot/connection-core 0.0.0 → 0.1.0

package/src/index.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ConnectionDependencyRouter,
+  decodeConnectionCommandIdV1,
+  decodeConnectionCommandV1,
+  decodeConnectionDependencyCommandV1,
+  decodeConnectionDependencyResultV1,
+  decodeConnectionModelCatalogV1,
+  decodeRevokeConnectionResultV1,
+  decodeStartConnectionResultV1,
+  type ConnectionDependencyCommandV1,
+} from "./index.js";
+
+describe("Connection result contracts", () => {
+  test("uses one recoverable command ID contract", () => {
+    expect(decodeConnectionCommandIdV1("command-1")).toBe("command-1");
+    expect(() =>
+      decodeConnectionCommandV1({
+        schemaVersion: 1,
+        type: "connection/refresh-models",
+        commandId: "lost response",
+        connectionId: "connection-1",
+      }),
+    ).toThrow("commandId is invalid");
+    expect(() => decodeConnectionCommandIdV1("lost response")).toThrow(
+      "commandId is invalid",
+    );
+  });
+
+  test("bounds advisory model catalogs", () => {
+    const model = {
+      providerModelId: "model:cloud",
+      displayName: "Model",
+      capabilities: { tools: false, vision: false, reasoning: false },
+      source: "discovered",
+    };
+
+    expect(() =>
+      decodeConnectionModelCatalogV1({
+        schemaVersion: 1,
+        generation: "catalog-1",
+        state: "fresh",
+        models: Array.from({ length: 101 }, () => model),
+      }),
+    ).toThrow("Connection model catalog is invalid");
+  });
+
+  test("requires exact versioned Connection start variants", () => {
+    expect(
+      decodeStartConnectionResultV1({
+        schemaVersion: 1,
+        status: "ready",
+        connectionId: "gmail-1",
+      }),
+    ).toEqual({
+      schemaVersion: 1,
+      status: "ready",
+      connectionId: "gmail-1",
+    });
+    expect(
+      decodeStartConnectionResultV1({
+        schemaVersion: 1,
+        status: "authorization-required",
+        connectionId: "gmail-1",
+        redirectUrl: "https://connect.example/authorize",
+        expiresAt: "2026-08-29T00:05:00.000Z",
+      }),
+    ).toMatchObject({ status: "authorization-required" });
+
+    for (const result of [
+      { schemaVersion: 1, connectionId: "gmail-1" },
+      { schemaVersion: 2, status: "ready", connectionId: "gmail-1" },
+      {
+        schemaVersion: 1,
+        status: "ready",
+        connectionId: "gmail-1",
+        redirectUrl: "https://connect.example/authorize",
+      },
+    ]) {
+      expect(() => decodeStartConnectionResultV1(result)).toThrow(
+        "Connection result is invalid",
+      );
+    }
+  });
+
+  test("strictly decodes provider-neutral dependency commands and results", () => {
+    const claim = {
+      schemaVersion: 1,
+      action: "claim",
+      operationId: "operation-1",
+      userId: "user-1",
+      packageId: "mail",
+      connectionId: "connection-1",
+      botId: "bot-1",
+      generation: "generation-1",
+      requirement: {
+        schemaVersion: 1,
+        packageId: "mail",
+        packageVersion: "1.0.0",
+        capabilityId: "send",
+        connectionTypeIds: ["oauth"],
+      },
+    } as const satisfies Extract<
+      ConnectionDependencyCommandV1,
+      { action: "claim" }
+    >;
+    expect(decodeConnectionDependencyCommandV1(claim)).toEqual(claim);
+    expect(
+      decodeConnectionDependencyResultV1({
+        schemaVersion: 1,
+        status: "pending",
+        failure: "provider response is uncertain",
+      }),
+    ).toMatchObject({ status: "pending" });
+    for (const invalid of [
+      { ...claim, extra: true },
+      { ...claim, requirement: { ...claim.requirement, extra: true } },
+      { schemaVersion: 1, status: "claimed", failure: "not allowed" },
+    ]) {
+      expect(() =>
+        "action" in invalid
+          ? decodeConnectionDependencyCommandV1(invalid)
+          : decodeConnectionDependencyResultV1(invalid),
+      ).toThrow();
+    }
+  });
+
+  test("routes only to a registered Connection-owning Contribution", async () => {
+    const router = new ConnectionDependencyRouter();
+    const command = {
+      schemaVersion: 1,
+      action: "read",
+      operationId: "operation-1",
+      userId: "user-1",
+      packageId: "mail",
+      connectionId: "connection-1",
+      botId: "bot-1",
+      generation: "generation-1",
+    } as const;
+    await expect(router.execute("missing", command)).resolves.toMatchObject({
+      status: "unavailable",
+    });
+    const calls: unknown[] = [];
+    router.register({
+      packageId: "mail",
+      executeDependency: (input) => {
+        calls.push(input);
+        return Promise.resolve({ schemaVersion: 1, status: "released" });
+      },
+    });
+    await expect(router.execute("mail", command)).resolves.toMatchObject({
+      status: "released",
+    });
+    expect(calls).toEqual([command]);
+  });
+
+  test("requires an exact versioned revocation result", () => {
+    expect(
+      decodeRevokeConnectionResultV1({
+        schemaVersion: 1,
+        status: "revoked",
+      }),
+    ).toEqual({ schemaVersion: 1, status: "revoked" });
+    for (const result of [
+      { status: "revoked" },
+      { schemaVersion: 2, status: "revoked" },
+      { schemaVersion: 1, status: "revoked", extra: true },
+    ]) {
+      expect(() => decodeRevokeConnectionResultV1(result)).toThrow(
+        "revocation result is invalid",
+      );
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,345 @@
+export * from "./authorization-state.js";
+export * from "./credentials.js";
+export * from "./models.js";
+
+export type StartConnectionResult =
+  | {
+      schemaVersion: 1;
+      status: "authorization-required";
+      connectionId: string;
+      redirectUrl: string;
+      expiresAt: string;
+      nativeReturnNonce?: string;
+    }
+  | {
+      schemaVersion: 1;
+      status: "ready";
+      connectionId: string;
+      nativeReturnNonce?: string;
+    };
+
+export interface RevokeConnectionResult {
+  schemaVersion: 1;
+  status: "revoked" | "reconciliation-required";
+}
+
+export interface ConnectionCompletionResult {
+  returnTarget: "browser" | "desktop";
+  status: "ready" | "pending" | "failed";
+  nativeReturnNonce?: string;
+}
+
+export interface ConnectionDependencyRequirementV1 {
+  schemaVersion: 1;
+  packageId: string;
+  packageVersion: string;
+  capabilityId: string;
+  connectionTypeIds: string[];
+}
+
+export type ConnectionDependencyCommandV1 =
+  | {
+      schemaVersion: 1;
+      action: "claim";
+      operationId: string;
+      userId: string;
+      packageId: string;
+      connectionId: string;
+      botId: string;
+      generation: string;
+      requirement: ConnectionDependencyRequirementV1;
+    }
+  | {
+      schemaVersion: 1;
+      action: "read" | "acknowledge" | "release" | "reconcile";
+      operationId: string;
+      userId: string;
+      packageId: string;
+      connectionId: string;
+      botId: string;
+      generation: string;
+    };
+
+export type ConnectionDependencyResultV1 =
+  | { schemaVersion: 1; status: "claimed" | "acknowledged" | "released" }
+  | {
+      schemaVersion: 1;
+      status: "pending" | "unavailable" | "absent" | "rejected";
+      failure?: string;
+    };
+
+export interface ConnectionDependencyOwner {
+  readonly packageId: string;
+  executeDependency(
+    command: ConnectionDependencyCommandV1,
+  ): Promise<ConnectionDependencyResultV1>;
+}
+
+/** Routes dependency commands only to the Contribution owning the Connection Package. */
+export class ConnectionDependencyRouter {
+  private readonly owners = new Map<string, ConnectionDependencyOwner>();
+
+  register(owner: ConnectionDependencyOwner): () => void {
+    if (this.owners.has(owner.packageId)) {
+      throw new Error(
+        `Connection dependency owner "${owner.packageId}" is already registered`,
+      );
+    }
+    this.owners.set(owner.packageId, owner);
+    return () => {
+      if (this.owners.get(owner.packageId) === owner)
+        this.owners.delete(owner.packageId);
+    };
+  }
+
+  async execute(
+    packageId: string,
+    input: unknown,
+  ): Promise<ConnectionDependencyResultV1> {
+    const command = decodeConnectionDependencyCommandV1(input);
+    const owner = this.owners.get(packageId);
+    if (!owner) {
+      return {
+        schemaVersion: 1,
+        status: "unavailable",
+        failure: `Connection Package "${packageId}" has no backend Contribution`,
+      };
+    }
+    return decodeConnectionDependencyResultV1(
+      await owner.executeDependency(command),
+    );
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function hasExactKeys(
+  value: Record<string, unknown>,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): boolean {
+  const allowed = new Set<PropertyKey>([...required, ...optional]);
+  const keys = Reflect.ownKeys(value);
+  return (
+    required.every((key) => Object.hasOwn(value, key)) &&
+    keys.every((key) => allowed.has(key))
+  );
+}
+
+function nonemptyString(value: unknown, maximum: number): value is string {
+  return (
+    typeof value === "string" && value.length > 0 && value.length <= maximum
+  );
+}
+
+function nativeReturnNonce(value: unknown): value is string | undefined {
+  return value === undefined || nonemptyString(value, 128);
+}
+
+export function decodeStartConnectionResultV1(
+  input: unknown,
+): StartConnectionResult {
+  const value = record(input);
+  if (
+    !value ||
+    value.schemaVersion !== 1 ||
+    !nonemptyString(value.connectionId, 128) ||
+    !nativeReturnNonce(value.nativeReturnNonce)
+  ) {
+    throw new Error("Connection result is invalid");
+  }
+  if (value.status === "ready") {
+    if (
+      !hasExactKeys(
+        value,
+        ["schemaVersion", "status", "connectionId"],
+        ["nativeReturnNonce"],
+      )
+    ) {
+      throw new Error("Connection result is invalid");
+    }
+    return {
+      schemaVersion: 1,
+      status: "ready",
+      connectionId: value.connectionId,
+      ...(value.nativeReturnNonce === undefined
+        ? {}
+        : { nativeReturnNonce: value.nativeReturnNonce }),
+    };
+  }
+  if (
+    value.status !== "authorization-required" ||
+    !hasExactKeys(
+      value,
+      ["schemaVersion", "status", "connectionId", "redirectUrl", "expiresAt"],
+      ["nativeReturnNonce"],
+    ) ||
+    !nonemptyString(value.redirectUrl, 8_192) ||
+    !nonemptyString(value.expiresAt, 64)
+  ) {
+    throw new Error("Connection result is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    status: "authorization-required",
+    connectionId: value.connectionId,
+    redirectUrl: value.redirectUrl,
+    expiresAt: value.expiresAt,
+    ...(value.nativeReturnNonce === undefined
+      ? {}
+      : { nativeReturnNonce: value.nativeReturnNonce }),
+  };
+}
+
+export function decodeRevokeConnectionResultV1(
+  input: unknown,
+): RevokeConnectionResult {
+  const value = record(input);
+  if (
+    !value ||
+    !hasExactKeys(value, ["schemaVersion", "status"]) ||
+    value.schemaVersion !== 1 ||
+    (value.status !== "revoked" && value.status !== "reconciliation-required")
+  ) {
+    throw new Error("revocation result is invalid");
+  }
+  return { schemaVersion: 1, status: value.status };
+}
+
+function dependencyIdentity(value: Record<string, unknown>) {
+  for (const key of [
+    "operationId",
+    "userId",
+    "packageId",
+    "connectionId",
+    "botId",
+    "generation",
+  ] as const) {
+    if (!nonemptyString(value[key], 128)) {
+      throw new Error(`Connection dependency ${key} is invalid`);
+    }
+  }
+  return {
+    operationId: value.operationId as string,
+    userId: value.userId as string,
+    packageId: value.packageId as string,
+    connectionId: value.connectionId as string,
+    botId: value.botId as string,
+    generation: value.generation as string,
+  };
+}
+
+function dependencyRequirement(
+  input: unknown,
+): ConnectionDependencyRequirementV1 {
+  const value = record(input);
+  if (
+    !value ||
+    !hasExactKeys(value, [
+      "schemaVersion",
+      "packageId",
+      "packageVersion",
+      "capabilityId",
+      "connectionTypeIds",
+    ]) ||
+    value.schemaVersion !== 1 ||
+    !nonemptyString(value.packageId, 128) ||
+    !nonemptyString(value.packageVersion, 100) ||
+    !nonemptyString(value.capabilityId, 128) ||
+    !Array.isArray(value.connectionTypeIds) ||
+    value.connectionTypeIds.length === 0 ||
+    value.connectionTypeIds.length > 64 ||
+    !value.connectionTypeIds.every((item) => nonemptyString(item, 128))
+  ) {
+    throw new Error("Connection dependency requirement is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    packageId: value.packageId,
+    packageVersion: value.packageVersion,
+    capabilityId: value.capabilityId,
+    connectionTypeIds: [...value.connectionTypeIds],
+  };
+}
+
+export function decodeConnectionDependencyCommandV1(
+  input: unknown,
+): ConnectionDependencyCommandV1 {
+  const value = record(input);
+  if (!value || value.schemaVersion !== 1) {
+    throw new Error("Connection dependency command is invalid");
+  }
+  const base = [
+    "schemaVersion",
+    "action",
+    "operationId",
+    "userId",
+    "packageId",
+    "connectionId",
+    "botId",
+    "generation",
+  ];
+  if (value.action === "claim") {
+    if (!hasExactKeys(value, [...base, "requirement"])) {
+      throw new Error("Connection dependency command is invalid");
+    }
+    return {
+      schemaVersion: 1,
+      action: "claim",
+      ...dependencyIdentity(value),
+      requirement: dependencyRequirement(value.requirement),
+    };
+  }
+  if (
+    value.action !== "read" &&
+    value.action !== "acknowledge" &&
+    value.action !== "release" &&
+    value.action !== "reconcile"
+  ) {
+    throw new Error("Connection dependency command is invalid");
+  }
+  if (!hasExactKeys(value, base)) {
+    throw new Error("Connection dependency command is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    action: value.action,
+    ...dependencyIdentity(value),
+  };
+}
+
+export function decodeConnectionDependencyResultV1(
+  input: unknown,
+): ConnectionDependencyResultV1 {
+  const value = record(input);
+  if (
+    !value ||
+    value.schemaVersion !== 1 ||
+    (value.status !== "claimed" &&
+      value.status !== "acknowledged" &&
+      value.status !== "released" &&
+      value.status !== "pending" &&
+      value.status !== "unavailable" &&
+      value.status !== "absent" &&
+      value.status !== "rejected") ||
+    !hasExactKeys(value, ["schemaVersion", "status"], ["failure"]) ||
+    (value.failure !== undefined && !nonemptyString(value.failure, 512))
+  ) {
+    throw new Error("Connection dependency result is invalid");
+  }
+  if (
+    (value.status === "claimed" ||
+      value.status === "acknowledged" ||
+      value.status === "released") &&
+    value.failure !== undefined
+  ) {
+    throw new Error("Connection dependency result is invalid");
+  }
+  return value.failure === undefined
+    ? { schemaVersion: 1, status: value.status }
+    : { schemaVersion: 1, status: value.status, failure: value.failure };
+}