Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { describe, expect, test } from "bun:test";
import { Composio, telemetry } from "@composio/core";
import {
BrokerAccountGoneError,
type BrokerConnection,
BrokerRefusalError,
BrokerUnconfiguredError,
brokerSentence,
type ComposioBroker,
} from "../src/plugins/broker";
import {
type ComposioActions,
LISTING_LIMIT,
vendorSentence,
} from "../src/plugins/composio";
import {
buildComposioClient,
createComposioClient,
} from "../src/plugins/composio-adapter";
import {
A_CRASH,
expectOnlyRefusal,
type RefusalName,
} from "./helpers/refusals";
/**
* The three facts about the adapter that a type checker cannot settle, asserted with no network.
*
* {@link buildComposioClient} takes the vendor OBJECT rather than an API key, and that is the whole
* reason this file can exist: every test below hands it a literal whose methods record what they
* were asked and answer from memory, so the adapter's own decisions are what is under test and
* nothing here dials Composio. A `createComposioClient` that only took a key would have made this
* file either a live test or no test at all.
*
* WHAT IS WORTH ASSERTING IS WHAT IS EASY TO GET SILENTLY WRONG. The mapping of the vendor's fields
* onto ours is one such thing — a listing that omitted its limit, or a catalogue row that read the
* wrong key for an action count, both answer plausibly and both are wrong in a way no exception
* reports. The refusal is the other: it is the one place this adapter is required to NOT make a
* vendor call, and an implementation that forwarded a mismatch would pass every test that only
* looked at what came back.
*/
/**
* The connection every fixture in this file resolves to, because none of them publishes a scheme.
*
* These rows were written to exercise the field mapping and the cache, so they carry a slug, a name
* and a meta and nothing about authentication — which is itself a readable answer: an app Composio
* says nothing about the auth of is one no flow here could run. It is named once rather than
* retyped into five assertions, so a change to the sentence is a change in one place.
*/
const NO_SCHEME: BrokerConnection = {
kind: "unsupported",
reason:
"Composio published no authentication scheme for this app, so there is no flow this deployment could run, and its own OAuth client is not something this deployment can register.",
};
/** A vendor method nothing in a given test should reach, which says so rather than answering. */
function refuse(what: string) {
return async (): Promise<never> => {
throw new Error(`${what} should not have been called in this test.`);
};
}
/**
* A vendor object whose every method refuses, with the few a test cares about substituted in.
*
* The refusals are the point rather than filler. A test about the catalogue that accidentally
* executed a tool, or one about a refusal that reached the vendor anyway, would otherwise fail on
* something unrelated — or, worse, pass. Here the unasked-for call names itself.
*/
function fakeVendor(parts: {
tools?: Record<string, unknown>;
toolkits?: Record<string, unknown>;
authConfigs?: Record<string, unknown>;
connectedAccounts?: Record<string, unknown>;
}) {
return {
tools: {
list: refuse("tools.list"),
getRawComposioToolBySlug: refuse("tools.getRawComposioToolBySlug"),
execute: refuse("tools.execute"),
...parts.tools,
},
toolkits: {
list: refuse("toolkits.list"),
retrieve: refuse("toolkits.retrieve"),
...parts.toolkits,
},
authConfigs: {
list: refuse("authConfigs.list"),
create: refuse("authConfigs.create"),
delete: refuse("authConfigs.delete"),
...parts.authConfigs,
},
connectedAccounts: {
list: refuse("connectedAccounts.list"),
link: refuse("connectedAccounts.link"),
create: refuse("connectedAccounts.create"),
delete: refuse("connectedAccounts.delete"),
...parts.connectedAccounts,
},
};
}
/**
* The page every listing here asks for, WRITTEN OUT rather than imported.
*
* AN ASSERTION THAT IMPORTS THE CONSTANT IT IS ABOUT CANNOT FAIL WHEN THAT CONSTANT MOVES, because
* both sides move together: each `limit` assertion below asked for whatever page the adapter had
* just decided to ask for, and `LISTING_LIMIT` 1000 -> 20 left all of them passing. The sibling
* `composio-transport.test.ts` writes its two numbers out for exactly this reason and documents it
* at length; this file imported one and called it pinned.
*
* So the literal lives here, and the imported constant is read in exactly one test below — which is
* where the argument for the number belongs: 1000 is the vendor's stated page ceiling and therefore
* the whole listing.
*/
const WHOLE_LISTING = 1000;
/**
* How many pages of one listing the adapter reads before it refuses, WRITTEN OUT for the reason
* {@link WHOLE_LISTING} is — and asserted exactly, for a reason of its own.
*
* `expect(calls).toBeLessThan(200)` stood against a ceiling of 50. That bound pins nothing: it
* passes at 50 pages, at 51, at 199, and at any ceiling anybody cares to raise it to short of the
* test's own runaway stop — which is to say it asserted that the paging terminated and called that
* an assertion about the ceiling. It was also green over the off-by-one it was the only test in a
* position to see: the adapter read 51 pages while its refusal said 50, because the ceiling was
* tested before the page it was counting had been recorded.
*
* So the number of pages READ and the number the refusal STATES are both asserted, and both
* against this literal.
*
* IT WAS 50 AND IT IS 200, WHICH IS A DELIBERATE CHANGE RATHER THAN A TEST FOLLOWING A MODULE. 50
* was argued from the only two listings that paged — one app's authorization configs and one
* person's accounts for one app — where a second page is already extraordinary. The app catalogue
* now pages too and is not that listing: Composio publishes more than {@link WHOLE_LISTING}
* toolkits, so its second page is the ordinary case. The module states the arithmetic; what matters
* here is that both numbers are written out, so a ceiling that moves again reddens the tests that
* are about it rather than redefining them.
*/
const PAGES_BEFORE_REFUSING = 200;
/** The page this deployment sends somebody back to once the consent screen is done with them. */
const RETURN_URL = "https://openbot.test/connections/x";
/**
* What Composio answers a withdrawal it actually performed, returned by every double that performs
* one.
*
* A DOUBLE THAT OMITS THIS IS NOT A DOUBLE OF THE VENDOR. `success` is a REQUIRED field of
* `ConnectedAccountDeleteResponse` — "indicates whether the connected account was successfully
* deleted" (`@composio/client` 0.1.0-alpha.76, `resources/connected-accounts.d.ts:7445-7451`) — and
* every fixture here used to answer `undefined`, which Composio cannot send. That was harmless only
* for as long as the adapter read nothing off the reply; the moment it started telling a performed
* delete from a declined one, a fixture answering nothing was a fixture asserting the adapter's
* behaviour against a reply no vendor produces.
*
* SPELLED AT EACH DOUBLE RATHER THAN DEFAULTED IN {@link fakeVendor}, for the reason the refusals
* there are spelled: the two tests next door hand back `{ success: false }` and `{}` on purpose,
* and a default would put the interesting answer and the ordinary one at different distances from
* the reader.
*/
const WITHDRAWN = { success: true };
/**
* What Composio answers a creation it actually performed, for the reason {@link WITHDRAWN} exists.
*
* `transformCreateAuthConfigResponse` builds this answer by reading `response.auth_config.id`
* (`@composio/core` 0.18.1, `src/utils/transformers/authConfigs.ts:96-106`), so an id is the one
* thing a created config comes back with. A double answering `undefined` is a double of a reply the
* vendor cannot send — harmless only for as long as the adapter read nothing off it, which is
* exactly the state that let a shape drift here report that nothing had been created over a config
* standing at Composio.
*/
const CREATED = { id: "ac_created" };
/**
* The three auth configs this file reasons about, named once rather than spelled at each fixture.
*
* Two of them are ours and one is an operator's dashboard work, and every decision the adapter
* makes about an app's configs is a decision about which of the three it is looking at. Naming
* them is what lets a fixture be written OUT of the order its assertion expects — see {@link MIXED}
* — instead of being an array whose index quietly carries the answer.
*/
const BY_HAND = { id: "ac_by_hand", name: "Linear", status: "ENABLED" };
const OURS = { id: "ac_ours", name: "Linear (OpenBot)", status: "ENABLED" };
/** The spare from a lost enable race: two administrators both found nothing and both created. */
const OURS_SPARE = {
id: "ac_ours_spare",
name: "Linear (OpenBot)",
status: "ENABLED",
};
/**
* The gmail config this deployment made, which is what a withdrawal is now allowed to reach.
*
* `revoke` READS THE CONFIGS BEFORE IT READS THE ACCOUNTS, which is why every fixture below that
* withdraws anything answers this listing. The account listing is scoped to the ids that come back
* from it, so a fixture that did not answer it would be describing a deployment with no config of
* its own — for which there is, correctly, nothing to withdraw — and every assertion about what the
* delete was asked would be an assertion about a call that never went out.
*
* ITS OWN CONSTANT RATHER THAN {@link OURS}, because the suffix is the whole of what the adapter
* reads and the rest of the name is the app an administrator typed. A gmail withdrawal answered
* with a config called "Linear (OpenBot)" would pass, and would leave the one fixture in this file
* that names the app it is about naming the wrong one.
*/
const OUR_GMAIL = {
id: "ac_gmail_ours",
name: "Gmail (OpenBot)",
status: "ENABLED",
};
/** An operator's own gmail config, carrying no suffix, which is the whole of what tells them apart. */
const BY_HAND_GMAIL = {
id: "ac_gmail_by_hand",
name: "Gmail",
status: "ENABLED",
};
/*
* THE VENDOR DOUBLES BELOW HONOUR THE QUERY THEY ARE HANDED, and that is half of what this file
* claims about every method that reads a listing.
*
* A double that hands back its rows whatever it was asked cannot tell a correct question from a
* wrong one. Every listing here used to be one: `connectedAccounts.list` answered `ca_1` to any
* person, any app and any set of statuses, and `authConfigs.list` answered gmail's config to a
* question about any app or about none. So the adapter asking about the WRONG PERSON, dropping a
* filter, or reading ANOTHER APP's configs passed every test that was not itself an assertion on
* the query's exact shape — and those were four tests, each of which pinned a query that happened
* to name `user_1` for both of the person's ids. `composio-grants-for.test.ts` and
* `arcade-adapter-connections.test.ts` closed the same blindness in their own files; this is that
* correction for the rest of the Composio adapter.
*
* So each listing double answers as the vendor does: a filter it is given narrows the rows, a
* filter it is NOT given does not — an account listing with no `userIds` is every person's, which
* is the defect at its worst — and every fixture carries rows the right question must leave out.
*/
/**
* The person every fixture here acts for, in the vendor's spelling.
*
* DIFFERENT FROM THE LOCAL `user_1` ON PURPOSE. `AccountRef` carries both, and every listing,
* link and creation goes out under `vendorUserId`; with the two spelled alike a call made under the
* local id read exactly like the right one.
*/
const VENDOR_USER = "composio_user_1";
/** The vendor's account statuses, so a fixture naming one it does not publish is a type error. */
type AccountStatus =
| "INITIALIZING"
| "INITIATED"
| "ACTIVE"
| "FAILED"
| "EXPIRED"
| "INACTIVE"
| "REVOKED";
/**
* A connected account as Composio holds it: the row it would send, and the facts its listing is
* filtered on, kept apart so the routing facts cannot reach the adapter as fields of the row.
*
* Every fact defaults to this file's ordinary case — {@link VENDOR_USER}'s ACTIVE, private gmail
* account on {@link OUR_GMAIL} — so a fixture spells only the fact it is about. `page` is the page
* of the listing the row sits on, for the tests about reading every page.
*/
type HeldAccount = {
row: unknown;
userId?: string;
toolkit?: string;
status?: AccountStatus;
authConfigId?: string;
shared?: boolean;
page?: number;
};
/** What the adapter asked an account listing, as the tests below assert it by name. */
type AccountQuery = {
userIds?: string[];
toolkitSlugs?: string[];
statuses?: string[];
accountType?: string;
authConfigIds?: string[];
limit?: number;
cursor?: string;
};
/**
* Accounts no question about {@link VENDOR_USER}'s gmail may return, whichever method is asking.
*
* One per filter the adapter is responsible for: somebody else's; one filed under the LOCAL id,
* which is a real vendor identity the moment anybody is ever given it; another app's; and a
* tombstone, which neither the gate nor the withdrawal counts. A listing that drops a filter, or
* asks under the wrong id, hands one of these back — and every test below then answers about it.
*/
const NOT_THIS_PERSONS_GMAIL: HeldAccount[] = [
{ row: { id: "ca_somebody_else" }, userId: "composio_user_2" },
{ row: { id: "ca_under_the_local_id" }, userId: "user_1" },
{ row: { id: "ca_another_app" }, toolkit: "slack" },
{ row: { id: "ca_tombstone" }, status: "REVOKED" },
];
/**
* And one the WITHDRAWAL may not reach although the gate counts it: this person's own account on a
* config an operator built by hand. `isConnected` asks of every config, so it is connected; `revoke`
* is scoped to configs this deployment made, so it is not this deployment's to delete.
*/
const ON_AN_OPERATORS_CONFIG: HeldAccount = {
row: { id: "ca_on_an_operators_config" },
authConfigId: BY_HAND_GMAIL.id,
};
/** Every account a question about {@link VENDOR_USER}'s gmail grants by THIS deployment must leave out. */
const DECOYS: HeldAccount[] = [
...NOT_THIS_PERSONS_GMAIL,
ON_AN_OPERATORS_CONFIG,
];
/**
* `connectedAccounts.list` as Composio answers it, with the queries it was asked.
*
* A filter that is present narrows; one that is absent does not, which is the vendor's own reading
* (`accountType` defaults to private accounts only). Pages are `page_<n>`, and a cursor is offered
* while any matching row sits on a later page.
*/
function accountListing(
held: HeldAccount[],
decoys: HeldAccount[] = DECOYS,
): { list: (query: unknown) => Promise<unknown>; asked: AccountQuery[] } {
const asked: AccountQuery[] = [];
const list = async (query: unknown) => {
const q = query as AccountQuery;
asked.push(q);
const matching = [...held, ...decoys].filter(
(account) =>
(q.userIds === undefined ||
q.userIds.includes(account.userId ?? VENDOR_USER)) &&
(q.toolkitSlugs === undefined ||
q.toolkitSlugs.includes(account.toolkit ?? "gmail")) &&
(q.statuses === undefined ||
q.statuses.includes(account.status ?? "ACTIVE")) &&
(q.authConfigIds === undefined ||
q.authConfigIds.includes(account.authConfigId ?? OUR_GMAIL.id)) &&
(q.accountType === "ALL" || account.shared !== true),
);
const page = q.cursor === undefined ? 1 : Number(q.cursor.slice(5));
const later = matching.some((account) => (account.page ?? 1) > page);
return {
items: matching
.filter((account) => (account.page ?? 1) === page)
.map((account) => account.row),
nextCursor: later ? `page_${page + 1}` : null,
};
};
return { list, asked };
}
/** The ordinary case: these rows are {@link VENDOR_USER}'s ACTIVE gmail accounts on our config. */
function heldAccounts(rows: unknown[]) {
return accountListing(rows.map((row) => ({ row }))).list;
}
/**
* Another app's config of ours, which a question about any other app must leave out.
*
* ITS ID SORTS FIRST, so an adapter that read the project's whole config listing — no `toolkit` —
* or another app's would take this one wherever it picks the first of ours.
*/
const OUR_SLACK = {
id: "ac_0_slack_ours",
name: "Slack (OpenBot)",
status: "ENABLED",
};
/**
* `authConfigs.list` as Composio answers it: scoped to the `toolkit` asked about, and the whole
* project's configs — {@link OUR_SLACK} among them — to a listing that names none.
*/
function configListing(toolkit: string, rows: unknown[]) {
const asked: unknown[] = [];
const byToolkit: Record<string, unknown[]> = {
slack: [OUR_SLACK],
[toolkit]: rows,
};
const list = async (query: unknown) => {
asked.push(query);
const named = (query as { toolkit?: string }).toolkit;
return {
items:
named === undefined
? Object.values(byToolkit).flat()
: (byToolkit[named] ?? []),
};
};
return { list, asked };
}
/** One app's configs, for a double that does not need the queries back. */
function configsOf(toolkit: string, rows: unknown[]) {
return configListing(toolkit, rows).list;
}
/**
* `tools.list` as Composio answers it: one app's actions to a listing naming that app, another
* app's to a listing naming that one, and every app's to a listing naming none.
*/
function actionsOf(toolkit: string, rows: unknown[]) {
const byToolkit: Record<string, unknown[]> = {
slack: [{ slug: "SLACK_SEND_MESSAGE", toolkit: { slug: "slack" } }],
[toolkit]: rows,
};
return async (query: unknown) => {
const named = (query as { toolkit_slug?: string }).toolkit_slug;
return {
items:
named === undefined
? Object.values(byToolkit).flat()
: (byToolkit[named] ?? []),
};
};
}
/** That listing as a vendor double, since every withdrawing fixture below needs the same one. */
const ourGmailConfig = configsOf("gmail", [OUR_GMAIL]);
/**
* The three sentences `authorize` can refuse with, told apart by the remedy each one prescribes.
*
* `rejects.toThrow(/linear/)` MATCHES ALL THREE, WHICH IS NOT A DETAIL. Deleting the no-config
* branch outright left this suite at 24 pass / 0 fail, because the call then fell through to the
* disabled branch and that sentence names the app too. The three remedies are three different acts
* by three different people — an administrator adding the app again, an operator enabling the
* config in Composio's own dashboard, and nobody at all because the app is not connected by
* visiting a page — so a test that cannot tell the sentences apart cannot tell a correct
* classification from a wrong one, which is the whole thing these refusals exist to get right.
*
* Each is the fragment of its own sentence that no other one contains, and each test below asserts
* its own AND the absence of the others.
*/
const NO_CONFIG_REMEDY =
/removing the app on its Plugins page and adding it again creates one/;
const DISABLED_REMEDY = /can enable it in Composio's dashboard/;
const NO_PAGE_REMEDY =
/connected by entering a credential rather than by visiting a page/;
/**
* The error a call raised, or a failure saying it answered where the test required a refusal.
*
* `rejects.toThrow(...)` cannot be followed by a second question about the SAME error — which kind
* it was, what else its sentence does not say — so every refusal assertion that wanted more than
* one fact about one throw had to settle for the first. This hands the error over instead.
*
* IT TOLD TWO LIES ABOUT ITS OWN FAILURES, and a helper every refusal in this file is read through
* is the last place a wrong answer about what happened should come from.
*
* `null` WAS BOTH ANSWERS AT ONCE. It was the value the resolve arm produced AND a value the reject
* arm can hand back — `Promise.reject(null)` is a rejection, and a vendor stub or an adapter path
* that raises a falsy value is exactly the kind of thing the tests below are written to catch — so
* a call that REFUSED with one was reported as "The call answered where this test requires it to
* have refused." That sends the reader to look for a missing guard when the guard fired. The two
* outcomes are now told apart by which arm ran rather than by the value it carried.
*
* `undefined` WAS RETURNED AS AN `Error` IT IS NOT. The cast made the type check and nothing else:
* the caller's very next line reads `.message` off it and the suite fails with the runtime's own
* "undefined is not an object", which is the phrasing this file's own {@link A_CRASH}
* exists to flag as a crash wearing a refusal's clothes — raised here, in the helper, about the
* test rather than about the adapter. A rejection that is not an `Error` has no message to read, so
* this says so itself instead of handing the caller something that will.
*/
async function failureOf(work: Promise<unknown>): Promise<Error> {
type Outcome = { refused: false } | { refused: true; raised: unknown };
const outcome = await work.then<Outcome, Outcome>(
() => ({ refused: false }),
(raised: unknown) => ({ refused: true, raised }),
);
if (!outcome.refused) {
throw new Error(
"The call answered where this test requires it to have refused.",
);
}
if (!(outcome.raised instanceof Error)) {
throw new Error(
`The call refused with ${
outcome.raised === null ? "null" : typeof outcome.raised
} rather than with an Error, so there is no message on it for this test to read.`,
);
}
return outcome.raised;
}
/*
* {@link A_CRASH} IS IMPORTED RATHER THAN DECLARED HERE, and it is asked of every refusal this file
* added after the shape sweep: a guard that is missing does not answer politely, it reads a field
* off `undefined` and hands an administrator a sentence naming a vendor method. It moved to
* `./helpers/refusals` because {@link expectOnlyRefusal} asks it of every sentence it grades, and
* two copies of one judgement about what a crash reads like is the drift this file legislates
* against everywhere else.
*/
/**
* The envelope guard's own sentence, so a test about a ROW can say it was not this one.
*
* `pageOf` refuses an answer that is not `{ items: [...] }` before any row reader sees a row, and
* every listing in {@link ComposioVendor} now comes off the RAW client, whose answers are envelopes
* — `{ items, next_cursor }` — rather than the bare arrays the SDK's transformers used to return.
* A fixture written as a bare array therefore dies at this guard, and a test asserting only "it
* refused in a sentence" passes on a refusal about the container while its name promises one about
* a field. Asserting the absence of this sentence is what makes the fixture's SHAPE load-bearing.
*/
const NOT_A_LISTING = /is not a listing at all/i;
/**
* Every sentence one failure carries, its own first and then the ones hanging off it.
*
* A COUNT IS A SENTENCE WITH ITS REASONS SOMEWHERE ELSE, which is why a question about what a reader
* was told cannot always be asked of `message` alone. `revoke` and `deleteAuthConfig` withdraw a SET
* and make the count their whole message on purpose — it is the part a reader can act on — and hang
* every refusal the loop met on `cause`, as one error or as an `AggregateError` of them. Asking only
* the first line there would grade those two methods on a wording that is deliberately not where
* their detail lives.
*/
function everythingSaidBy(error: unknown, depth = 0): string[] {
if (!(error instanceof Error) || depth > 4) return [];
const carried =
error instanceof AggregateError
? error.errors.flatMap((one) => everythingSaidBy(one, depth + 1))
: [];
return [
error.message,
...carried,
...everythingSaidBy(error.cause, depth + 1),
];
}
describe("the page size this file is written against", () => {
test("the module's ceiling is still the number every assertion here spells out", () => {
// The one place the imported constant is read. Changing `LISTING_LIMIT` reddens exactly this
// test, which is where the argument for the number lives, rather than silently moving every
// assertion in the file to whatever the module has just decided.
expect(LISTING_LIMIT).toBe(WHOLE_LISTING);
});
});
describe("listing an app's actions", () => {
test("the caller's page reaches the vendor, so the vendor's default never applies", async () => {
const asked: unknown[] = [];
const gmailActions = actionsOf("gmail", [
{
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
description: "Fetch emails from Gmail.",
input_parameters: { type: "object", properties: {} },
tags: ["readOnlyHint"],
version: "20260903_00",
toolkit: { slug: "gmail" },
},
]);
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async (query: unknown) => {
asked.push(query);
return gmailActions(query);
},
},
}),
);
const listed = await actions.listActions("gmail", {
limit: WHOLE_LISTING,
});
// An omitted limit is not "no opinion": Composio's page defaults to 20, and the wrapper this
// listing used to go through additionally set `important=true` whenever a toolkit query carried
// no limit, no tags and no search (`@composio/core` 0.18.1, `src/models/Tools.ts:505-515`), so
// the short answer was also a filtered one and nothing in it said so. The request is composed
// here now, which is why the assertion is on the query and not on the answer: the limit, the
// toolkit version the wrapper used to supply, and no `important` at all.
expect(asked).toEqual([
{
toolkit_slug: "gmail",
limit: WHOLE_LISTING,
toolkit_versions: "latest",
},
]);
expect(listed).toEqual([
{
slug: "GMAIL_FETCH_EMAILS",
description: "Fetch emails from Gmail.",
inputParameters: { type: "object", properties: {} },
tags: ["readOnlyHint"],
version: "20260903_00",
},
]);
});
test("a page of no rows is refused rather than dropped on the way to the vendor", async () => {
const asked: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async (query: unknown) => {
asked.push(query);
// Twenty rows: Composio's own default page, which is what a dropped limit produced.
return {
items: Array.from({ length: 20 }, (_, index) => ({
slug: `GMAIL_ACTION_${index}`,
})),
};
},
},
}),
);
const refusal = await failureOf(actions.listActions("gmail", { limit: 0 }));
/*
* THE REASON MOVED AND THE REFUSAL DID NOT. Through the wrapper a zero did not travel short —
* it did not travel: `getRawComposioTools` composed its request with `...(limit ? { limit } :
* {})` (`@composio/core` 0.18.1, `src/models/Tools.ts:536`) over a schema spelling the field
* `z.number().optional()` with no floor (`src/types/tool.types.ts:257`), so it went out with no
* limit and came back as Composio's own page of twenty. The raw client passes a zero through,
* so that particular substitution is gone. What is left is the argument that never rested on
* it: the page is required on this seam precisely so that no layer supplies one quietly, and a
* caller asking for no rows is a fault to report rather than one to correct on their behalf.
*/
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/0 rows is not a page/);
expect(refusal.message).toMatch(/tools already held are untouched/);
// Nothing went out, which is the point: the fault is in the request, not in the answer.
expect(asked).toEqual([]);
});
});
describe("the app catalogue", () => {
test("a toolkit becomes the row an administrator chooses from", async () => {
const asked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async (query: unknown) => {
asked.push(query);
return {
items: [
{
slug: "gmail",
name: "Gmail",
is_local_toolkit: false,
meta: {
description: "Send and read mail.",
logo: "https://logos.composio.dev/gmail.png",
categories: [
{ id: "productivity", name: "Productivity" },
{ id: "email", name: "Email" },
],
tools_count: 63,
},
},
// A toolkit that publishes none of the optional fields, because several do. An
// administrator picking from a few hundred apps is better served by a missing logo
// than by a broken one, so the absence has to survive as null rather than as "".
{
slug: "sparse",
name: "Sparse",
is_local_toolkit: false,
meta: {},
},
],
};
},
},
}),
);
const apps = await broker.listApps();
// Pages at the documented ceiling, ordered by usage so the apps anybody actually connects come
// first, and carrying no cursor field on the first request. No search term: the catalogue is
// held for ten minutes and searched in this process by both of its callers, so a per-term
// request would be a per-term cache.
expect(asked).toEqual([{ limit: WHOLE_LISTING, sort_by: "usage" }]);
expect(apps).toEqual([
{
slug: "gmail",
name: "Gmail",
description: "Send and read mail.",
logo: "https://logos.composio.dev/gmail.png",
categories: ["Productivity", "Email"],
actionCount: 63,
// Composio measures none of the three, so each is an explicit null: "not measured", which is
// a different fact from "measured, and none" and must never be read through a `?? 0`.
classifiedCount: null,
permissionCount: null,
scopedActionCount: null,
connection: NO_SCHEME,
},
{
slug: "sparse",
name: "Sparse",
description: "",
logo: null,
categories: [],
actionCount: 0,
// Composio measures none of the three, so each is an explicit null: "not measured", which is
// a different fact from "measured, and none" and must never be read through a `?? 0`.
classifiedCount: null,
permissionCount: null,
scopedActionCount: null,
connection: NO_SCHEME,
},
]);
});
});
/**
* The catalogue's lifetime, asserted by counting what the vendor was asked rather than what came
* back.
*
* THE COST BEING AVOIDED IS NOT HYPOTHETICAL. The admin picker's search field debounces and then
* asks `/composio/apps`, which filters the whole directory in this process because Composio's
* toolkit listing takes no search term — so without a cache each distinct term a person types pulls
* a few hundred rows over the wire, and pressing Add pulls them once more. Every test here therefore
* asserts a CALL COUNT: an implementation that answered correctly and asked five times would pass
* any assertion that only looked at the rows.
*
* The clock is the builder's second argument, which is why these can be written at all. Each
* {@link buildComposioClient} holds its own cache, so a test starts from an empty one by building,
* and moves time by assigning rather than by waiting ten minutes.
*/
describe("holding the catalogue", () => {
/** The one row these tests map, kept out of the way of what they are actually asserting. */
const GMAIL = {
slug: "gmail",
name: "Gmail",
meta: { description: "Send and read mail.", tools_count: 63 },
};
const GMAIL_ROW = {
slug: "gmail",
name: "Gmail",
description: "Send and read mail.",
logo: null,
categories: [],
actionCount: 63,
// Composio measures none of the three, so each is an explicit null: "not measured", which is
// a different fact from "measured, and none" and must never be read through a `?? 0`.
classifiedCount: null,
permissionCount: null,
scopedActionCount: null,
connection: NO_SCHEME,
};
test("a second listing inside the window asks the vendor nothing", async () => {
let calls = 0;
let clock = 1_000_000;
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => {
calls += 1;
return { items: [GMAIL] };
},
},
}),
() => clock,
);
const first = await broker.listApps();
// Nine minutes is a person searching, choosing and enabling: the whole interaction this cache
// exists for happens inside one window.
clock += 9 * 60 * 1000;
const second = await broker.listApps();
expect(calls).toBe(1);
expect(first).toEqual([GMAIL_ROW]);
expect(second).toEqual([GMAIL_ROW]);
});
test("a listing after the window asks again, and answers with what it just read", async () => {
let calls = 0;
let clock = 1_000_000;
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => {
calls += 1;
// The catalogue moves between the two reads, which is the only way to tell a second
// request apart from a cache that happened to be asked twice.
return calls === 1
? { items: [GMAIL] }
: {
items: [
GMAIL,
{
slug: "linear",
name: "Linear",
meta: { tools_count: 12 },
},
],
};
},
},
}),
() => clock,
);
await broker.listApps();
clock += 10 * 60 * 1000 + 1;
const later = await broker.listApps();
expect(calls).toBe(2);
expect(later).toEqual([
GMAIL_ROW,
{
slug: "linear",
name: "Linear",
description: "",
logo: null,
categories: [],
actionCount: 12,
// Composio measures none of the three, so each is an explicit null: "not measured", which is
// a different fact from "measured, and none" and must never be read through a `?? 0`.
classifiedCount: null,
permissionCount: null,
scopedActionCount: null,
connection: NO_SCHEME,
},
]);
});
test("callers arriving while a listing is in flight share the one request", async () => {
let calls = 0;
let answer: (page: { items: unknown[] }) => void = () => {};
const inFlight = new Promise<{ items: unknown[] }>((resolve) => {
answer = resolve;
});
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: () => {
calls += 1;
return inFlight;
},
},
}),
() => 1_000_000,
);
// Not awaited between the two, because that is the case: three people opening the picker
// together, or one debounce firing twice, all arrive before the first answer exists. A cache
// that held the ROWS rather than the request would be empty for every one of them.
const both = Promise.all([broker.listApps(), broker.listApps()]);
answer({ items: [GMAIL] });
const [first, second] = await both;
expect(calls).toBe(1);
expect(first).toEqual([GMAIL_ROW]);
expect(second).toEqual([GMAIL_ROW]);
});
test("a refusal is not held, so the next caller asks the vendor again", async () => {
let calls = 0;
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => {
calls += 1;
// The real first failure here is a key that is unset or wrong, and the operator who
// fixes it presses the button again within seconds. A cached refusal would keep
// refusing for ten minutes with nothing left to fix.
if (calls === 1) throw new Error("Composio refused the catalogue.");
return { items: [GMAIL] };
},
},
}),
() => 1_000_000,
);
await expect(broker.listApps()).rejects.toThrow(/refused/);
// The clock has not moved: the window is still open and it is the FAILURE rather than the
// window that must not be remembered.
const recovered = await broker.listApps();
expect(calls).toBe(2);
expect(recovered).toEqual([GMAIL_ROW]);
});
});
describe("executing an action", () => {
test("an action belonging to another app is refused before anything is sent", async () => {
const executed: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
toolkit: { slug: "gmail" },
}),
execute: async (...call: unknown[]) => {
executed.push(call);
return { data: {}, error: null, successful: true };
},
},
}),
);
// The gate in `./access` cleared this person for slack, because slack is what the connection's
// url names. The slug was recorded by some earlier listing, and Composio's execute takes the
// slug ALONE — there is no toolkit field on the wire — so forwarding this would run a Gmail
// action under a gate that only ever looked at a Slack connection.
const refused = actions.execute(
{
toolkit: "slack",
slug: "GMAIL_FETCH_EMAILS",
userId: "user_1",
version: "20260903_00",
},
{ max_results: 5 },
);
// Both apps are named, because a reader holding only one of them cannot tell whether the url
// is wrong or the recorded action is.
const refusal = await failureOf(refused);
expect(refusal.message).toMatch(/slack/);
expect(refusal.message).toMatch(/gmail/);
// AND THE STEP, because a sentence that names both apps and stops there leaves the reader
// holding a contradiction with nothing to do about it. The url this action was recorded under
// has changed, and refreshing the app's tools is what reconciles the two.
expect(refusal.message).toMatch(
/Refreshing this app's tools on its Plugins page/,
);
expect(executed).toEqual([]);
});
/**
* WHOSE CALL IT IS, WHICH NOTHING IN THIS FILE WAS ASKING.
*
* Every test around this one is about a call being REFUSED, and each asserts that nothing went
* out. Not one asserted what goes out when the call is allowed — so the three fields that decide
* what a successful call MEANS were covered by nobody. `userId` is the whole of a tool call's
* attribution to a person: it is what Composio resolves to a connected account, so replacing it
* with a literal runs one person's action against somebody else's mailbox, and the audit row this
* deployment writes afterwards names the wrong human. `version` is what stops a recorded action
* being run at whatever Composio publishes today. `arguments` is the call itself.
*
* ASSERTED AS THE WHOLE CALL RATHER THAN FIELD BY FIELD, because an extra field on this request is
* as much a finding as a missing one — `allowMultiple`, a session id, a modifier — and a per-field
* assertion is blind to every one of them.
*
* THE RESOLVE IS ASSERTED TOO, for the reason the execute is. It is the round trip this adapter
* spends on purpose, and the version it carries is what decides WHICH definition of the action the
* app-mismatch check below is made against.
*/
test("a call that runs carries the person, the version and the arguments", async () => {
const resolved: unknown[] = [];
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async (...call: unknown[]) => {
resolved.push(call);
return {
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
toolkit: { slug: "gmail" },
};
},
execute: async (...call: unknown[]) => {
ran.push(call);
return { data: { messages: [] }, error: null, successful: true };
},
},
}),
);
const answer = await actions.execute(
{
toolkit: "gmail",
slug: "GMAIL_FETCH_EMAILS",
// DELIBERATELY NOT THE `user_1` EVERY OTHER FIXTURE HERE USES. A literal standing in for
// the caller's id is the mutation this test exists to catch, and the file's own house id is
// the one literal a mutation would plausibly be — so a person named after nothing else is
// what makes the assertion able to tell attribution from coincidence.
userId: "user_whose_mailbox_this_is",
version: "20260903_00",
},
{ max_results: 5 },
);
expect(resolved).toEqual([
["GMAIL_FETCH_EMAILS", { version: "20260903_00" }],
]);
expect(ran).toEqual([
[
"GMAIL_FETCH_EMAILS",
{
arguments: { max_results: 5 },
userId: "user_whose_mailbox_this_is",
version: "20260903_00",
},
],
]);
// And the vendor's answer crosses the seam as itself: this adapter adds nothing to a result and
// takes nothing off one.
expect(answer).toEqual({
data: { messages: [] },
error: null,
successful: true,
});
});
/**
* AND THE ACCOUNT, WHERE THE CALLER MEANT ONE IN PARTICULAR.
*
* CRITERION. A call carrying `connectedAccountId` sends it to Composio under that name, beside
* the three fields the test above pins. A call carrying none sends no such key at all, which is
* what the whole-body assertion above already holds this to.
*
* REASON. A person and an app are not a name for an account. Composio takes one account per set
* of credentials, one person may hold several for one app — a second mailbox, a stale account
* beside a fresh one — and the vendor picks which of them an unpinned call runs in. For a Bot's
* tool call that is right, and nothing here names an account. For a VERIFICATION it is the whole
* meaning of the answer: `connectBrokeredWithFields` spends one call to find out whether the key
* it has just attached works, and unpinned that call was answered by the person's OTHER account —
* verifying a key nothing had tried, or condemning a good one, and deleting the account it had
* just made, because some older account of theirs was broken.
*
* ASSERTED AT THE WIRE because this is the only place it can be. The field is the vendor's own —
* `ToolExecuteParams` carries it — and every layer above this one can pass it perfectly while
* this adapter drops it, which is exactly what it did: the seam had no such field, so the store
* could not have sent one.
*/
test("a call that names an account sends it as the connected account", async () => {
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
toolkit: { slug: "gmail" },
}),
execute: async (...call: unknown[]) => {
ran.push(call);
return { data: {}, error: null, successful: true };
},
},
}),
);
await actions.execute(
{
toolkit: "gmail",
slug: "GMAIL_FETCH_EMAILS",
userId: "user_whose_mailbox_this_is",
version: "20260903_00",
connectedAccountId: "ca_the_one_just_made",
},
{},
);
// The whole body again, for that test's reason: an extra field on this request is as much a
// finding as a missing one.
expect(ran).toEqual([
[
"GMAIL_FETCH_EMAILS",
{
arguments: {},
userId: "user_whose_mailbox_this_is",
version: "20260903_00",
connectedAccountId: "ca_the_one_just_made",
},
],
]);
});
});
/**
* Minting one person's connect link, which is the call that decides whether consent comes back.
*
* `connectedAccounts.link` RATHER THAN `toolkits.authorize`, and the difference is the whole
* subject of these two tests. `toolkits.authorize` takes a user id, a toolkit and an optional auth
* config id and has nowhere to put a callback, so every consent it started ended on Composio's own
* hosted page: the person had granted access and the only way back to this deployment was to find
* it again by hand. `link` carries the callback, and it is also the vendor's own named replacement
* for `initiate` on Composio-managed OAuth, which is exactly what `ensureAuthConfig` creates here.
*
* The auth config is READ rather than created, because this deployment already made it when an
* administrator enabled the app — named for this deployment, visible in an operator's dashboard.
* `toolkits.authorize` would have created one on demand at Composio's defaults, which is the
* behaviour enabling-time creation exists to replace.
*/
describe("beginning one person's connection", () => {
test("the link carries the page this deployment sends them back to", async () => {
const linked: unknown[] = [];
const { list, asked: listed } = configListing("linear", [
{
id: "ac_this_deployments",
name: "Linear (OpenBot)",
status: "ENABLED",
},
]);
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list },
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const begun = await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/composio-linear",
});
// The config this deployment already holds for the app — and no `authConfigs.create`, which
// would refuse in `fakeVendor` if it were reached. The listing asks for disabled configs too,
// because a config it cannot see is one `ensureAuthConfig` would create a second of.
expect(listed).toEqual([
{ toolkit: "linear", limit: WHOLE_LISTING, showDisabled: true },
]);
expect(linked).toEqual([
[
VENDOR_USER,
"ac_this_deployments",
{
callbackUrl: "https://openbot.test/connections/composio-linear",
},
],
]);
expect(begun).toEqual({
redirectUrl: "https://backend.composio.dev/s/a-link",
// Declared null: Composio's return leg is correlated by sealed state, not by a broker id.
authorizationId: null,
});
});
test("an app with no auth config is a refusal naming an administrator's step", async () => {
/*
* The state is real rather than defensive: an app enabled before this deployment created
* configs at all, or a config deleted by hand in Composio's dashboard. Creating one here
* instead would mint it unnamed, at the vendor's managed defaults, at the moment somebody
* pressed Connect — and nothing would be minted for the person to visit either way, so the
* honest answer names the app and the step that fixes it.
*/
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", []) },
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const refused = broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/composio-linear",
});
const refusal = await failureOf(refused);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/linear/);
// THE REMEDY AND NOT THE APP'S NAME. All three of this method's refusals name the app, so
// `/linear/` passes whichever branch was taken and the branch under test could be deleted
// outright without reddening anything. What distinguishes this state is what fixes it.
expect(refusal.message).toMatch(NO_CONFIG_REMEDY);
expect(refusal.message).not.toMatch(DISABLED_REMEDY);
expect(refusal.message).not.toMatch(NO_PAGE_REMEDY);
// And nothing was begun at the vendor: a link against a config chosen by nobody would attach
// this person's account to a configuration this deployment cannot see or tighten.
expect(linked).toEqual([]);
});
});
/**
* Choosing WHICH auth config, which is a question this file used to answer with "the first one".
*
* An auth config lives in the project the API key belongs to, beside any an operator built by hand
* in Composio's own dashboard, and the vendor's listing has no documented order. So "the first row"
* is a coin toss between an object this deployment created and an object it knows nothing about —
* and the two callers tossed it separately, so they could land on different rows. The name is the
* only provenance Composio offers: {@link CONFIG_SUFFIX} is written into it at creation for exactly
* this, and was then read by nobody.
*/
describe("telling this deployment's auth configs from anybody else's", () => {
/**
* What a listing of one app's configs looks like when an operator has been in the dashboard.
*
* SPELLED OUT OF THE ORDER THE ASSERTIONS EXPECT, which is what makes the sort the thing under
* test rather than scenery. Composio documents no order for this listing; `configsMadeHere`
* filters to ours and then sorts on the id, and every fixture this file used to hold was already
* id-ordered — so the sort could be replaced with a plain copy and all 24 tests stayed green.
* Here the spare arrives FIRST and sorts SECOND, so a filter alone answers `ac_ours_spare` where
* every assertion below names `ac_ours`, and the delete's order is the sort's rather than the
* vendor's.
*/
const MIXED = [OURS_SPARE, BY_HAND, OURS];
test("a connection is begun against the config this deployment made, not the first row", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", MIXED) },
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/x",
});
// A connection is a lasting attachment to whatever config it was made against: scopes, tool
// restrictions and a lifetime this deployment neither chose nor can read. Attaching somebody to
// the hand-made one is not a mistake a later call can correct.
expect(linked).toEqual([
[
VENDOR_USER,
"ac_ours",
{ callbackUrl: "https://openbot.test/connections/x" },
],
]);
});
test("an app whose only config was made by hand is refused rather than borrowed", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [BY_HAND]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const refused = broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/x",
});
const refusal = await failureOf(refused);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
// The same state as an app with no configs at all — none of OURS — so the same remedy, and
// not the disabled one: the config that exists here is enabled, and enabling it again is
// advice that would send an operator to a dashboard to change nothing.
expect(refusal.message).toMatch(NO_CONFIG_REMEDY);
expect(refusal.message).not.toMatch(DISABLED_REMEDY);
expect(linked).toEqual([]);
});
test("removing an app drops every config of ours and leaves the hand-made one standing", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
// Both of ours go — leaving one behind would leave live grants — and the hand-made
// one stands. The listing arrives spare-first, so the order asserted below is the sort's
// and not the vendor's.
list: configsOf("linear", MIXED),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
await broker.deleteAuthConfig("linear");
// `revoke_on_delete` on each, because the endpoint soft-deletes and revokes nothing without it
// — and this is the one call that reaches an account whose local row drifted away.
expect(deleted).toEqual([
["ac_ours", { revoke_on_delete: true }],
["ac_ours_spare", { revoke_on_delete: true }],
]);
});
test("a config left standing is a failure, and the count is the message", async () => {
/*
* THE TWIN OF THE PARTIAL REVOKE, WHICH HAD TWO TESTS WHILE THIS HAD NONE — so this throw
* could be deleted with the whole suite green. The caller is `removeServer`, which deletes the
* app's row once this returns: a config left standing is a live grant that the removal was
* supposed to end, and nothing in this deployment can find it again afterwards.
*
* The count is asserted rather than the fact of a refusal, because the count is the whole
* remedy: an operator who reads that one of two went knows that pressing remove again finishes
* the job rather than repeats it.
*/
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", MIXED),
delete: async (id: string) => {
if (id === "ac_ours_spare") {
throw new Error("Composio refused that one.");
}
},
},
}),
);
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(
/removed 1 of this deployment's 2 authorization configs for linear/,
);
});
test("an app whose configs no longer carry this deployment's name is not a clean removal", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
/*
* THE CONFIG THIS DEPLOYMENT MADE, RENAMED IN COMPOSIO'S DASHBOARD. Same object, same
* grants on it, same accounts connected against it; the one field that changed is the
* only one this file writes and the only one it can recognise itself by.
*/
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear", status: "ENABLED" },
]),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
/*
* QUIET IS THE FAILURE HERE, AND IT IS THE ONE NOTHING REPORTS. `deleteAuthConfig` returning
* normally lets `removeServer` delete the app's row, which is the last thing in this
* deployment naming the app — so an administrator reads that the app was withdrawn while the
* config and every grant made against it stand at Composio with nothing pointing at them.
*/
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal).not.toBeInstanceOf(AggregateError);
expect(refusal.message).not.toMatch(A_CRASH);
// The count of what is standing and the marker that would claim it, which together are the
// whole remedy: an operator can look at one config and see which of the two readings it is.
expect(refusal.message).toMatch(/Composio holds 1 for linear/);
expect(refusal.message).toMatch(/\(OpenBot\)/);
/*
* AND NOTHING WAS DELETED, which is the half this refusal is not allowed to trade away. The
* row carries no marker, so deleting it is as likely to destroy an operator's own dashboard
* work — with every account on THAT — as it is to finish the removal.
*/
expect(deleted).toEqual([]);
});
/**
* AND THAT REFUSAL PROMISES THE REMOVAL WILL GO THROUGH, WHICH AN UNREADABLE ROW MAKES FALSE.
*
* `readableConfigs` sorts every row into one of two piles, so "configs that are legible and carry
* nobody's suffix" and "rows this deployment could not read at all" are facts about the same
* listing and arrive together as readily as either arrives alone. The refusal above fired first
* and closed with "only taking it out of that dashboard leaves this app with nothing standing,
* after which the removal goes through" — a promise the unreadable row makes untrue, since the
* next press meets the refusal this method raises for exactly that pile. The operator is sent to
* do one act and told it finishes the job, and the clause saying otherwise was suppressed by a
* branch about different rows.
*/
test("an unreadable row is still reported beside configs that carry nobody's name", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_theirs", name: "Linear", status: "ENABLED" },
{ id: "ac_nameless", status: "ENABLED" },
]),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// The renamed-config reading, which is the one this refusal already carried.
expect(refusal.message).toMatch(/Composio holds 1 for linear/);
expect(refusal.message).toMatch(/\(OpenBot\)/);
// And the row that was never sorted, whose remedy is the same dashboard and whose existence is
// what stops the sentence promising a removal that would go through.
expect(refusal.message).toMatch(/no id or no name/);
// Nothing is deleted either way: the whole refusal is about not guessing which row is whose.
expect(deleted).toEqual([]);
});
/**
* A CONFIG ROW THE LISTING NAMED TWICE IS ONE CONFIG, NOT TWO — the twin of the account dedupe
* that landed a wave earlier, one function away, and was not brought here.
*
* The paging loop guards against the vendor repeating a CURSOR and not against it repeating a
* ROW: a page boundary crossed while a config is created, or a proxy stitching two overlapping
* pages together, hands one id over twice with the cursor advancing perfectly each time. The
* second delete of that config then meets Composio's "there is no such auth config", which
* arrives as a refusal — so a removal that had in fact COMPLETED was counted as partial,
* `removeServer` never deleted the app's row, and every retry met the same duplicate and failed
* in the same place. An app in that state can never be removed.
*
* THE DOUBLE REFUSES THE SECOND DELETE OF ONE CONFIG, which is what the vendor does and what
* makes this test able to fail. A stub that answered both identically would be green against an
* adapter that sent the delete twice.
*/
test("a config the listing named twice is removed once", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async (query: unknown) =>
(query as { cursor?: string }).cursor === undefined
? { items: [OURS], nextCursor: "page_2" }
: { items: [OURS], nextCursor: null },
delete: async (id: string) => {
if (deleted.includes(id)) {
throw new Error(
`Composio holds no auth config with the id ${id}.`,
);
}
deleted.push(id);
},
},
}),
);
await broker.deleteAuthConfig("linear");
expect(deleted).toEqual(["ac_ours"]);
});
/**
* AND THE COUNT IN A REAL PARTIAL REMOVAL IS OF CONFIGS, NOT OF ROWS — the same pairing the
* account dedupe has, for the same reason: an inflated denominator is a figure nothing measured,
* in the one sentence an operator is meant to act on.
*/
test("a duplicated row is not a third config in the sentence a partial removal carries", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [OURS, OURS, OURS_SPARE]),
delete: async (id: string) => {
if (id === "ac_ours_spare") {
throw new Error("Composio refused that one.");
}
},
},
}),
);
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(
/removed 1 of this deployment's 2 authorization configs for linear/,
);
});
/**
* AND A REPEATED ROW WHOSE SECOND COPY IS UNREADABLE IS STILL ONE CONFIG, NOT A REFUSAL.
*
* CRITERION. Where the listing repeats an id already accepted and the repeat carries no readable
* name, nothing is added to `unreadable`: the config is deleted and the removal completes.
*
* REASON. The id de-duplication ran BELOW the name guard, so a second sighting of an already-read
* id was still pushed into `unreadable` if that copy's name could not be read — which contradicts
* the invariant the function states for itself, ONE ID IS ONE CONFIG HOWEVER MANY TIMES THE
* LISTING NAMED IT. The paged listing repeating `ac_ours` across a page boundary is the same race
* the test above is written for, and the repeat can perfectly well arrive mid-rename in the
* dashboard, or stitched by a proxy out of two partial reads, as `{ id, name: null }`.
*
* WHAT IT COST IS A REFUSAL AFTER THE WORK WAS DONE. `configs` held the one readable copy and
* `unreadable.length` was 1, so this method deleted the config, succeeded, and THEN threw "…and
* the app has not been fully withdrawn" — over a config that was already gone. `removeServer`
* treats that as a failure, so the app's row stayed on the Plugins page behind a removal that had
* completed, and every retry met the same repeat and failed in the same place.
*/
test("a repeated row whose second copy has no readable name is still one config", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async (query: unknown) =>
(query as { cursor?: string }).cursor === undefined
? { items: [OURS], nextCursor: "page_2" }
: // The same config, named again with a name this deployment cannot read.
{ items: [{ ...OURS, name: null }], nextCursor: null },
delete: async (id: string) => {
deleted.push(id);
},
},
}),
);
// Completes rather than refusing, which is the assertion: the throw used to come AFTER the
// delete below had already gone through.
await broker.deleteAuthConfig("linear");
expect(deleted).toEqual(["ac_ours"]);
});
/**
* AND THE OTHER ORDERING ANSWERS THE SAME, WHICH IS WHAT MAKES IT ONE CONFIG RATHER THAN ONE ROW.
*
* CRITERION. Where the UNREADABLE copy of a repeated id arrives first and the readable copy
* second, the config is still deleted and the removal still completes.
*
* REASON. The fix above dropped the repeat before the name was read, which closed
* good-copy-first and opened its mirror: the id was claimed by whichever copy came first, so an
* unreadable first copy took the slot, the readable second copy returned at the de-duplication
* test, and the config never reached `configs` at all. `deleteAuthConfig` then left standing a
* config the other ordering would have deleted — one listing, two answers, decided by which side
* of a page boundary the vendor happened to put the good row on.
*
* NEITHER ORDERING IS MORE LIKELY THAN THE OTHER. A rename in flight in Composio's dashboard, or
* a proxy stitching two partial reads, is as free to hand the half-written row over first as
* second, so a function whose verdict depends on that is deciding on a coin toss.
*/
test("a repeated row read second is still the config, however the listing ordered the copies", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async (query: unknown) =>
(query as { cursor?: string }).cursor === undefined
? // The same config, named first with a name this deployment cannot read.
{ items: [{ ...OURS, name: null }], nextCursor: "page_2" }
: { items: [OURS], nextCursor: null },
delete: async (id: string) => {
deleted.push(id);
},
},
}),
);
await broker.deleteAuthConfig("linear");
expect(deleted).toEqual(["ac_ours"]);
});
/**
* A ROW THAT COULD NOT BE READ MUST NOT BLOCK THE CONNECTION IT HAS NOTHING TO DO WITH.
*
* Reading the configs used to throw on the first row it could not check, so one unreadable row
* refused every call that reads this listing — including this one, where a config of ours was
* read, is ENABLED, and is the right thing to attach somebody to whatever else the listing held.
* The person is told the vendor's shape is wrong about an app they can perfectly well connect.
*/
test("an unreadable row does not stop a connection against the config that was readable", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_nameless", status: "ENABLED" },
OURS,
]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
expect(linked).toEqual([
[VENDOR_USER, "ac_ours", { callbackUrl: RETURN_URL }],
]);
});
/**
* AND WHERE THERE IS NOTHING OF OURS TO GO ON, THE REMEDY IS NOT THE ONE FOR AN APP WITH NO
* CONFIG. "Remove the app and add it again" is a loop that cannot close in this state: the
* removal meets its own refusal over the same unreadable row, and so does the enable. The
* sentences are told apart by their remedies here for the reason {@link NO_CONFIG_REMEDY} exists.
*/
test("a listing this deployment cannot read is not an app with no config", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [{ id: "ac_nameless" }]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
/*
* THE THIRD SENTENCE IS ASSERTED AND NOT ONLY THE OTHER TWO'S ABSENCE. This named what the
* refusal must not be — an app with no config, a config Composio calls disabled — and left
* what it IS to any third sentence, including one prescribing an act nobody on that page can
* perform. Its twin one method over (`connectWithFields`, in "a listing this deployment cannot
* read is not an app that publishes nothing") already asserts its own remedy, so the pair now
* reads the one condition the one way.
*/
expectOnlyRefusal(refusal.message, "unreadableNobodySent");
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
// And nobody was sent anywhere: a link is a lasting attachment to one config, so it is never
// minted off a listing this deployment could not read.
expect(linked).toEqual([]);
});
/**
* AND NOTHING IS CREATED BESIDE A ROW THAT MIGHT ALREADY BE OURS, which is the one caller of the
* four that must refuse rather than act on what it can name. A second config is not a duplicate
* but a SPLIT: two populations of connections for one app, and a removal later that drops half.
*/
test("a row this deployment cannot read stops a second config being created", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [{ id: "ac_nameless" }]),
create: async (...call: unknown[]) => {
created.push(call);
return CREATED;
},
},
}),
);
const refusal = await failureOf(
broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(created).toEqual([]);
});
test("an app Composio holds no configs for at all is still a quiet removal", async () => {
/*
* THE HALF THE REFUSAL ABOVE MUST NOT SWALLOW. Removing an app has to be able to happen twice:
* an app can be removed, re-enabled and removed again, two administrators can press the button
* together, and an app enabled before this deployment created configs at all has none to drop.
* In each of those the end state is the one that was asked for, so a throw would report a
* failure to somebody who got exactly what they wanted — and an implementation that reached
* green above by refusing whenever it deleted nothing would do precisely that.
*
* AND IT SAYS SO RATHER THAN LEAVING IT TO BE INFERRED, which it did not: this test held no
* assertion at all. What it actually pinned was "the call did not throw", which a reader has to
* reconstruct from the absence of an `expect` — and the other half, that nothing was deleted,
* rested on {@link fakeVendor}'s stub refusing, where a call that WAS made and a call that was
* not both end the test the same way round. Both halves are stated here.
*/
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", []),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
await expect(broker.deleteAuthConfig("linear")).resolves.toBeUndefined();
expect(deleted).toEqual([]);
});
test("a disabled config of ours stops a second one being created", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
// Disabled configs are asked for, because this listing is what decides whether to create.
// A listing that omitted them would find nothing and create the split it exists to stop.
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: "DISABLED" },
]),
create: async (...call: unknown[]) => {
created.push(call);
},
},
}),
);
await broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
});
expect(created).toEqual([]);
});
test("a disabled config is a refusal rather than a link that cannot work", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: "DISABLED" },
]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const refused = broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/x",
});
// Sending somebody to consent against a disabled config spends their consent and attaches
// nothing, and nothing on the page they are on can fix it. The act that DOES fix it is an
// operator's in Composio's own dashboard, which is the one thing the no-config sentence next
// door never says — so that is what this asserts.
const refusal = await failureOf(refused);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(DISABLED_REMEDY);
expect(refusal.message).not.toMatch(NO_CONFIG_REMEDY);
expect(linked).toEqual([]);
});
/**
* AND HOLDING A DISABLED CONFIG BESIDE AN UNSETTLED ONE IS NOT A REASON TO BE TOLD ABOUT ONE.
*
* More than one config of ours is an ordinary outcome of a lost enable race, which this file says
* for itself — so the two states the `ENABLED` test falls through into can and do arrive on one
* listing. They were chained: the unsettled rows were reported and the disabled ones were not,
* which leaves a reader with the one remedy nobody on that page can act on ("upgrade
* `@composio/core`") while the act that WOULD have got them connected — enabling the disabled
* config in Composio's dashboard — was withheld by the presence of a row it says nothing about.
* The same chain, and the same suppression, that `revoke`'s clause list was corrected for.
*/
test("a disabled config beside an unsettled one is told both remedies", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_a", name: "Linear (OpenBot)", status: "DISABLED" },
{ id: "ac_b", name: "Linear (OpenBot)", status: "PENDING" },
]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
// The row whose state Composio would not name, whose only remedy is a package upgrade.
expect(refusal.message).toMatch(/neither ENABLED nor DISABLED/);
// And the one an administrator can act on today, which the chain was withholding.
expect(refusal.message).toMatch(DISABLED_REMEDY);
// Still a refusal either way: consent spent against a config that is not enabled attaches
// nothing and cannot be spent again without sending the person round a second time.
expect(linked).toEqual([]);
});
test("an app with only somebody else's config still gets one of our own", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [BY_HAND]),
create: async (...call: unknown[]) => {
created.push(call);
return CREATED;
},
},
}),
);
await broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
});
// Adopting the hand-made one would have this deployment mint connections against scopes it
// cannot see and delete an operator's work when the app is removed.
expect(created).toEqual([
[
"linear",
{ type: "use_composio_managed_auth", name: "Linear (OpenBot)" },
],
]);
});
});
/**
* WHAT ENABLING AN APP ACTUALLY CREATES, WHICH IS A DIFFERENT ANSWER FOR EACH KIND OF APP.
*
* Every config this deployment ever made was `use_composio_managed_auth`, which is the right answer
* for exactly one of the five kinds. The other four were wrong in four different ways, and only one
* of them announced itself: Composio answers 404 for an app that has no managed OAuth client of its
* own, so Linear's MCP app was unconnectable. The rest were quiet — a no-auth app whose creation
* the vendor refuses outright, a key app whose people were sent to a consent screen with nothing to
* ask them, and an app this deployment cannot drive at all, enabled anyway.
*
* THE ASSERTIONS ARE ON WHAT WENT OUT, AND ON WHAT DID NOT. Two of these four are about a call that
* must not be made at all, which no assertion on a return value can see: {@link fakeVendor}'s
* refusals name the unasked-for call, and the counters here say which door was not opened.
*/
describe("the config each kind of app is enabled with", () => {
test("a self-registering app gets a custom config with no credentials in it", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear_mcp", []),
create: async (...call: unknown[]) => {
created.push(call);
return CREATED;
},
},
}),
);
await broker.ensureAuthConfig({
toolkit: "linear_mcp",
name: "Linear MCP",
connection: { kind: "self-registering" },
});
/*
* `DCR_OAUTH` AND NO CREDENTIALS, which is the whole of what such an app needs: the vendor
* registers a client of its own against the provider at connect time. The managed type is what
* this used to send and it is the one answer that cannot work here — Composio has no OAuth
* client of its own for these apps, so the managed path answers 404 and nobody connects.
*/
expect(created).toEqual([
[
"linear_mcp",
{
type: "use_custom_auth",
authScheme: "DCR_OAUTH",
name: "Linear MCP (OpenBot)",
credentials: {},
},
],
]);
});
test("a key app gets a custom config carrying no secret, because the secret is per person", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("perplexityai", []),
create: async (...call: unknown[]) => {
created.push(call);
return CREATED;
},
},
}),
);
await broker.ensureAuthConfig({
toolkit: "perplexityai",
name: "Perplexity",
connection: { kind: "fields", authScheme: "API_KEY" },
});
/*
* NO KEY ON THE CONFIG, AND THAT IS NOT AN OMISSION TO BE FIXED LATER. The config is
* per-deployment and the key is one person's; it belongs to each connection made against this
* config, which is where the connect form sends it. A key here would be one person's secret
* shared by everybody the app is enabled for.
*/
expect(created).toEqual([
[
"perplexityai",
{
type: "use_custom_auth",
authScheme: "API_KEY",
name: "Perplexity (OpenBot)",
credentials: {},
},
],
]);
});
test("a no-auth app gets no config at all, because Composio refuses one", async () => {
let listed = false;
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => {
listed = true;
return { items: [] };
},
},
}),
);
await broker.ensureAuthConfig({
toolkit: "hackernews",
name: "Hacker News",
connection: { kind: "no-auth" },
});
/*
* NOT EVEN THE LISTING, which is the half that is easy to leave in. Composio's own refusal is
* "Cannot create an auth config for toolkit hackernews because it does not require
* authentication. You can use its tools directly without creating a connected account." — so
* there is nothing to find and nothing to create, and a read made anyway is a round trip whose
* answer no branch below could use. `create` is left at {@link fakeVendor}'s refusal, which
* names itself if it is ever reached.
*/
expect(listed).toBe(false);
});
test("an unsupported app is refused before anything is created", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("docusign", []),
},
}),
);
const refusal = await failureOf(
broker.ensureAuthConfig({
toolkit: "docusign",
name: "DocuSign",
connection: {
kind: "unsupported",
reason: "needs its own OAuth client",
},
}),
);
/*
* THE DERIVATION'S OWN SENTENCE, carried rather than restated. It is the one the picker filters
* on and the one an administrator has already read beside the app; a second sentence invented
* here would be a second account of why the app cannot be driven, and the two would drift.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/needs its own OAuth client/);
expect(refusal.message).toMatch(/docusign/);
expect(refusal.message).not.toMatch(A_CRASH);
});
});
/**
* Ending somebody's access, which is the claim this whole surface is here to be able to make.
*
* THE DELETE DOES NOT REVOKE, and that is the vendor's own description of it: it "soft-deletes a
* connected account by marking it as deleted in the database", preserving the record, unless
* `revoke_on_delete` is passed. Every path that says it ended somebody's access — a person
* disconnecting, an app being removed, a person being offboarded — runs through this method and
* wrote `true` into the audit trail while the refresh token at Google was untouched. The assertions
* here are therefore on WHAT WENT OUT rather than on what came back: an implementation that dropped
* the flag answers every one of them identically.
*/
describe("withdrawing one person's grants", () => {
test("the delete asks for the upstream credentials to be revoked", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
delete: async (...call: unknown[]) => {
deleted.push(call);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
expect(deleted).toEqual([["ca_1", { revoke_on_delete: true }]]);
});
test("a delete Composio answered `success: false` is not a withdrawal", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
// A 200 whose body says the account was not deleted. The flag went out, Composio read
// the request and answered it — this is the vendor declining, not failing.
delete: async () => ({ success: false }),
},
}),
);
/*
* WITHOUT THE CHECK THIS ANSWERS `true`, WHICH IS THE WHOLE FINDING. `store.ts` writes that
* boolean into `mcp.account_disconnected` as `vendorRevocationRequested` and then deletes the
* `composio_connections` row — the only thing in this deployment naming which app this person
* connected. So a `success: false` nobody read ends as a trail entry claiming a grant was
* withdrawn, an account that is still live at Google, and nothing left pointing at it.
*
* ASSERTED AS A REFUSAL AND AS A COUNT, because "did not answer true" is satisfied by a crash.
*/
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(
/withdrew 0 of this person's 1 accounts for gmail/,
);
expect(refusal.message).not.toMatch(A_CRASH);
// The reason lives on `cause`, because the count is deliberately the whole of the sentence.
expect(everythingSaidBy(refusal).join(" ")).toMatch(/success: false/);
});
test("a delete whose verdict Composio did not send is not counted as one either", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
/*
* `success` IS REQUIRED IN THE DECLARATION AND ABSENT ON THIS WIRE, which is the shape
* the check has to survive rather than the one it is for. `@composio/client` parses the
* body and hands it over, so the schema's "required" is a promise about what Composio
* means to send and not a fact about what arrived.
*/
delete: async () => ({}),
},
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
/*
* A DIFFERENT SENTENCE FROM THE ONE NEXT DOOR, and that is what this asserts. "Composio said
* no" is a fact about this account that a second press can meet again; "Composio answered
* something this deployment cannot read" is a fact about the package, correctable by nobody
* holding an admin page. Collapsing them would send an operator to press a button for a
* condition a button cannot change.
*/
const said = everythingSaidBy(refusal).join(" ");
expect(said).toMatch(/upgrading this deployment's @composio\/core/);
expect(said).not.toMatch(/success: false/);
});
/**
* AND NO DOCUMENT AT ALL IS NOT A DOCUMENT WITH ITS VERDICT MISSING.
*
* The delete comes off `@composio/client`, which parses the body and hands it over — the
* declaration on {@link ComposioVendor} says so, and the test above rests on it for `{}`. So an
* answer that is a bare string reaches this read as readily as the empty document does, and
* `("deleted").success` is `undefined`, not a throw: the refusal said "Composio sent nothing where
* its verdict belongs, and that field is the only thing in the reply", which asserts a reply with
* one field missing about an answer that was not a reply. The shape is the finding.
*/
test("a withdrawal answered with something that is not a document names the answer, not a missing verdict", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
delete: async () => "deleted",
},
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
const said = everythingSaidBy(refusal).join(" ");
expect(said).toMatch(/sent a string where its reply to the withdrawal/);
expect(said).not.toMatch(/where its verdict/);
expect(said).toMatch(/upgrading this deployment's @composio\/core/);
});
test("the listing asks about every state a grant can be hiding in", async () => {
// Nothing of this person's to withdraw — only the accounts every filter must leave out.
const { list, asked } = accountListing([]);
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: { list },
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(false);
/*
* `accountType` because its default is private accounts only, so a shared account is invisible
* to a listing that omits it — and an invisible account is a live grant this answers `false`
* about. The statuses because an unfinished consent or a lapsed token is still something a
* provider is holding. `REVOKED` is the one left out: it is the only status that says the grant
* is already gone, and deleting a tombstone would have this report a withdrawal that never was.
*
* AND `authConfigIds`, WHICH THIS ASSERTION USED TO SAY WAS ABSENT. It was written out as the
* whole query on the reasoning that the breadth is the point — and it is, for three of the four
* parameters. The fourth is the opposite: omitting it asks about every authorization config in
* the project, including ones an operator built by hand in Composio's dashboard, and this
* listing is the one that decides what gets deleted with `revoke_on_delete`. The assertion was
* therefore pinning the defect in place, which is why it moved rather than being relaxed.
*/
expect(asked).toEqual([
{
userIds: [VENDOR_USER],
toolkitSlugs: ["gmail"],
statuses: [
"INITIALIZING",
"INITIATED",
"ACTIVE",
"FAILED",
"EXPIRED",
"INACTIVE",
],
accountType: "ALL",
authConfigIds: [OUR_GMAIL.id],
limit: WHOLE_LISTING,
},
]);
});
test("being connected is a narrower question, and asked as one", async () => {
// SHARED, so the `true` below is only reachable through `accountType: "ALL"`: the vendor's
// default is private accounts only, and a listing that dropped it would answer `false` here.
const { list, asked } = accountListing([
{ row: { id: "ca_1" }, shared: true },
]);
const { broker } = buildComposioClient(
fakeVendor({ connectedAccounts: { list } }),
);
expect(
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
// ACTIVE only — an unfinished or expired account must not tell somebody their app is wired up —
// but `accountType: "ALL"` all the same, because a shared account is a connected account.
expect(asked).toEqual([
{
userIds: [VENDOR_USER],
toolkitSlugs: ["gmail"],
statuses: ["ACTIVE"],
accountType: "ALL",
limit: WHOLE_LISTING,
},
]);
});
test("nobody with no account for the app is answered no", async () => {
/*
* NOT AN EMPTY LISTING, WHICH ANSWERS `false` TO EVERY QUESTION, RIGHT OR WRONG. The vendor
* holds somebody else's gmail account, one filed under this person's LOCAL id, this person's
* account for another app, a revoked one and an expired one — and an adapter that asked about
* the wrong person, or dropped any filter, finds one of them and opens the gate.
*/
const { list, asked } = accountListing(
[{ row: { id: "ca_expired" }, status: "EXPIRED" }],
NOT_THIS_PERSONS_GMAIL,
);
const { broker } = buildComposioClient(
fakeVendor({ connectedAccounts: { list } }),
() => 1_000_000,
);
/*
* THE ONLY TEST IN THIS FILE THAT CAN FAIL A GATE THAT ALWAYS OPENS. Both assertions about
* `isConnected` expected `true`, so `async isConnected() { return true }` was green — and a
* gate that cannot answer no is a gate that lets every call through, which is exactly the
* question `./access` asks this method before running somebody's action.
*/
expect(
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(false);
// And it was a question that was asked, rather than a `false` reached without one.
expect(asked.map((query) => query.userIds)).toEqual([[VENDOR_USER]]);
});
/**
* AND THE STATUS FILTER IS A MODULE'S OWN ARRAY, WHICH IS NOT SOMETHING TO HAND ACROSS A SEAM.
*
* `CONNECTED` and `REVOCABLE` are written once at the top of the adapter and were passed straight
* into the vendor's listing body, so the array the vendor was handed WAS the constant. A vendor
* that sorted, normalised or appended to what it was given would not corrupt one call: it would
* corrupt the constant, for the life of the process, and the next question asked with it would be
* filtered by something nobody wrote down. It is the same sharing the catalogue's copy exists to
* end, one seam over and with no ten-minute expiry to bound it — `isConnected` is the gate
* `./access` asks before running somebody's action, and `REVOCABLE` decides what a disconnect can
* even see.
*/
test("the statuses a listing is filtered by are not the adapter's own array", async () => {
const asked: string[][] = [];
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
list: async (query: unknown) => {
const statuses = (query as { statuses: string[] }).statuses;
asked.push([...statuses]);
// All it takes is a recipient that tidies up what it was handed.
statuses.push("DELETED");
return { items: [] };
},
},
}),
() => 1_000_000,
);
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
});
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
});
expect(asked).toEqual([["ACTIVE"], ["ACTIVE"]]);
});
test("a refusal partway through still asks about the accounts behind it", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_2" }, { id: "ca_3" }]),
delete: async (id: string) => {
if (id === "ca_2") throw new Error("Composio refused that one.");
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
const refused = broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
});
// The third account is the whole point: a throw at the second used to abandon it, so a grant
// nobody ever asked about outlived a call that reported only the failure of a different one.
await expect(refused).rejects.toThrow(/2 of this person's 3 accounts/);
expect(deleted).toEqual(["ca_1", "ca_3"]);
});
test("a partial withdrawal is a failure rather than a reported disconnection", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_2" }]),
delete: async (id: string) => {
if (id === "ca_2") throw new Error("Composio refused that one.");
return WITHDRAWN;
},
},
}),
);
/*
* NOT A `true`. `store.ts` revokes and only then deletes the `composio_connections` row, which
* is the only thing naming which app this person connected; a `true` here deletes that row, the
* trail records a disconnection, and the account this call could not end is left live with
* nothing pointing at it. The throw leaves the row standing, so pressing disconnect again is a
* second attempt with everything the first one had.
*/
await expect(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).rejects.toBeInstanceOf(BrokerRefusalError);
});
/**
* AN ACCOUNT THIS DEPLOYMENT CANNOT NAME MUST NOT STOP IT WITHDRAWING THE ONES IT CAN.
*
* The id check used to run over every row BEFORE any delete went out, so one row whose id
* Composio omitted threw ahead of the first withdrawal — and the next attempt met the same row
* and threw in the same place. A person with three grants and one unreadable row could never
* withdraw any of them, for ever, and the page told them to try again.
*
* THE TWO FAILURES THIS SITS BETWEEN ARE BOTH WORSE, which is why the answer is neither of them. A
* delete sent with `undefined` where an id belongs is a request Composio may read as anything,
* followed by a `true` and an audit row saying this person's access ended. Refusing before
* anything goes out is a permanent block over a row nobody can remove from here. What a person is
* owed is the withdrawal of every grant this deployment CAN name, and a sentence counting what
* was left — which is a state they can act on, by removing the rest in Composio's own dashboard.
*/
test("an account with no id does not stop the accounts beside it being withdrawn", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: null }, { id: "ca_3" }]),
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// Both readable grants gone, and no delete sent for the row that had no id: a withdrawal of
// `undefined` is the request this whole guard exists to stop being made.
expect(deleted).toEqual(["ca_1", "ca_3"]);
// STILL A FAILURE, because `store.ts` deletes the `composio_connections` row on a `true` and
// that row is the only thing in this deployment naming which app this person connected.
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).toMatch(/2 of this person's 3 accounts/);
/*
* And the reason the third could not be asked about is named, because "try again" is not the
* remedy for it and the reader would otherwise be given a count with no way to read it.
*
* THE ROW AND THE LISTING RATHER THAN THE WORD. This asked `/id/` of `cause`, and `/id/` is
* inside "invalid", "considered", "provided" and "identifier" — so it asserted almost nothing
* about which reading produced the cause, and would not have noticed this sentence being
* rewritten in the neighbouring listing's words. `withdrawableAccounts` and `readableConfigs`
* raise the same fault over two different listings one function apart.
*/
expectOnlyRefusal(
everythingSaidBy(failure).join("\n"),
"accountId",
"row 2 of its gmail accounts for this person",
);
});
/**
* AND A CONFIG ROW THIS DEPLOYMENT CANNOT READ MUST NOT STOP IT EITHER — the same correction as
* the account above, one listing earlier, where it was still live after that one landed.
*
* Reading the configs threw on the first row it could not check, and the withdrawal reads them
* BEFORE it reads a single account. So one unreadable config row meant a person could never
* withdraw anything for that app: every press met the same row and the same throw, ahead of the
* first delete, with their readable grants standing the whole time. What they are owed is the
* withdrawal of every grant this deployment can reach and a sentence about what it could not.
*/
test("a config row that could not be read does not stop the grants behind the one that could", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("gmail", [{ id: "ac_gmail_nameless" }, OUR_GMAIL]),
},
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// The grant on the config that WAS readable is gone, which is the half a throw ahead of the
// loop threw away.
expect(deleted).toEqual(["ca_1"]);
// And still a failure, because a grant of theirs may sit on the config that could not be read
// and nothing here ever asked about it — so `store.ts` must not delete the row that names this
// person's connection.
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).not.toMatch(A_CRASH);
expect(failure.message).toMatch(/withdrew 1 of this person's 1 accounts/);
expect(failure.message).toMatch(/authorization configs for gmail/);
/*
* And the reason that row could not be sorted travels as `cause`, because the sentence above is
* deliberately a count and leaves the reasons nowhere else to live.
*
* ASKED AS THE NAME GUARD'S OWN CLAUSE AND NOT AS THE WORD "name". `readableConfigs` has two
* row guards and the id guard's sentence carries the word too — "the id is the whole of what a
* deletion NAMES" — so `/name/` matched either of them, and the two guards reading each
* other's field left this test green. Measured, not supposed.
*/
expectOnlyRefusal(
everythingSaidBy(failure).join("\n"),
"configName",
"row 1 of Composio's authorization configs for gmail",
);
});
/**
* AND A LISTING WHOSE ONLY FINDING IS AN UNREADABLE CONFIG ROW IS ITS OWN STATE, WHICH IS THE
* BRANCH EVERY SIBLING OF THIS METHOD HAS AND THIS ONE DID NOT.
*
* With a config of ours that IS readable and no account on it, the partial-withdrawal throw at
* the end of this method was what answered: "Composio withdrew 0 of this person's 0 accounts for
* gmail." Both figures are counts of a set nothing measured, in the one sentence a reader is
* meant to act on, and "withdrew" asserts that some withdrawal happened. Nothing was withdrawn
* and nothing was there to withdraw. {@link ComposioBroker.deleteAuthConfig} was corrected for
* the identical sentence about configs — "removed 0 of this deployment's 0" — and this is the
* same count one listing further in.
*
* STILL A REFUSAL, which is the half that does not move: a grant of this person's may sit on the
* config behind the row nothing could sort, so `store.ts` must not delete the row that names
* their connection.
*/
test("a person with no account and one unsortable config row is told that, not a count of nothing", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("gmail", [{ id: "ac_gmail_nameless" }, OUR_GMAIL]),
},
connectedAccounts: { list: heldAccounts([]) },
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).not.toMatch(A_CRASH);
// No count of a set nothing measured, in either position.
expect(failure.message).not.toMatch(/withdrew \d+ of this person's \d+/);
// And the reason the question could not be settled travels, as it does on every sibling branch.
expectOnlyRefusal(
everythingSaidBy(failure).join("\n"),
"unreadableNoAccountWithdrawn",
undefined,
["configName"],
);
});
/**
* THE GATE IS A COUNT AND WAS ASKING FOR AN ID IT NEVER USES.
*
* `isConnected` answers whether this person holds an ACTIVE account for an app, which is a
* question about how many rows came back — the id is the revoke's business and nothing this
* question reads. Taking the ids anyway meant an account Composio described without one turned a
* true answer into a thrown refusal: the person IS connected, and the gate that refuses their run
* says so on the strength of a field it was never going to look at.
*/
test("an account the vendor described without an id still counts as connected", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: { list: heldAccounts([{}]) },
}),
() => 1_000_000,
);
expect(
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
});
/**
* AN OPERATOR'S OWN AUTHORIZATION CONFIG IS NOT THIS DEPLOYMENT'S TO EMPTY.
*
* The account listing was asked by person, by app and by "all account types" and by nothing else,
* so it returned every account Composio holds for that pair — including ones attached to a config
* an operator built by hand in their dashboard, for purposes this deployment knows nothing about,
* and including the SHARED ones other people are acting through. Each of those was then deleted
* with `revoke_on_delete`, which tears the grant up at the provider. One person pressing
* disconnect on their own settings page ended somebody else's integration, silently, and answered
* `true`.
*
* WHICH IS THE PRINCIPLE `deleteAuthConfig` ALREADY STATES ONE LEVEL UP: it refuses to delete a
* config it cannot show is this deployment's, on exactly the reasoning that an operator's
* dashboard work is not ours to destroy. The accounts hanging off that config are the same work.
*
* ASSERTED ON WHAT WENT OUT, because an implementation that asked the unscoped question and then
* deleted everything it found answers this test's `true` just as confidently.
*/
test("the withdrawal asks only about accounts on configs this deployment made", async () => {
const deleted: string[] = [];
// {@link DECOYS} carries this person's own gmail account on the operator's config, so an
// unscoped question hands it back and the delete below names it.
const { list, asked } = accountListing([{ row: { id: "ca_1" } }]);
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
// An operator's beside ours, which is the state the whole guard is about. Out of the
// vendor's order, so a reader that took the first row would take the wrong one.
list: configsOf("gmail", [BY_HAND_GMAIL, OUR_GMAIL]),
},
connectedAccounts: {
list,
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
// The operator's config is not in the question, so no account on it can be in the answer and
// none of them can reach the delete.
expect(asked.map((query) => query.authConfigIds)).toEqual([[OUR_GMAIL.id]]);
expect(deleted).toEqual(["ca_1"]);
});
/**
* NOTHING AT ALL IS NOTHING TO WITHDRAW, AND IT IS ANSWERED WITHOUT ASKING.
*
* `authorize` mints every connect link against a config this deployment made and refuses where
* there is none, so an app Composio holds no configs for never had a connection begun through it.
* Listing accounts anyway could only turn up somebody else's, and the one thing this call does
* with an account it turns up is delete it.
*
* THE ASSERTION IS THE DOUBLE. `connectedAccounts.list` is left at {@link fakeVendor}'s refusal,
* so an implementation that asked the question at all fails here by name — which is a stronger
* statement than the `false` beside it, because a listing scoped to an EMPTY set of configs would
* answer `false` too while putting a filter on the wire that the far side is free to read as no
* filter at all.
*/
test("a person's accounts are not listed where Composio holds no config for the app", async () => {
const { broker } = buildComposioClient(
fakeVendor({ authConfigs: { list: configsOf("gmail", []) } }),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(false);
});
/**
* AND "NONE OF OURS" IS NOT THAT STATE — THE SEVENTH ROUTE TO A REVOCATION THAT DID NOT REVOKE.
*
* THIS TEST ASSERTED THE `false`, AND THE `false` WAS THE DEFECT. It stood on the reasoning above
* — none of ours means nothing was ever granted through this app — which is sound about an app
* Composio holds no configs for and cannot tell that app from this one. An operator renames a
* config in Composio's dashboard, dropping the suffix or editing the app's title past it, and
* this deployment's own live grants read as somebody else's work: `store.ts` then writes
* `vendorRevocationRequested: false` into the audit trail and deletes the `composio_connections`
* row, so the person's grant stands at the provider with nothing naming it and the trail records
* that no withdrawal was even asked for. The assertion is changed on purpose, and the case it
* used to cover — Composio holding nothing at all — is asserted next door, where it is true.
*
* `deleteAuthConfig` HAS REFUSED IN EXACTLY THIS STATE SINCE THE WAVE BEFORE THIS ONE, which is
* what makes this a disagreement rather than a judgement call: two halves of removing an app's
* access read one condition two different ways, one function apart.
*
* THE DOUBLE IS STILL THE OTHER HALF OF THE ASSERTION. `connectedAccounts.list` is left refusing,
* so an implementation that answered this by listing somebody else's accounts — and then deleting
* what it found — fails here by name.
*/
test("an app whose configs no longer carry this deployment's name is not a quiet disconnection", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("gmail", [BY_HAND_GMAIL]) },
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// The count standing and the marker that would have claimed it, which is the same pair
// `deleteAuthConfig` hands an operator for the same state and the same one act in a dashboard.
expect(refusal.message).toMatch(/Composio holds 1 for gmail/);
expect(refusal.message).toMatch(/\(OpenBot\)/);
});
/**
* A WITHDRAWAL THAT HAPPENED, REPORTED AS A FAILURE — the guard for `success: false` overreaching.
*
* The installed client resolves two answers with no document at all: a 204 becomes `null`
* ("fetch refuses to read the body when the status code is 204") and a JSON reply carrying
* `content-length: 0` becomes `undefined` (`@composio/client` 0.1.0-alpha.76,
* `src/internal/parse.ts:16-42`). Neither can be a rejection the vendor made: every `!response.ok`
* is thrown as an `APIError` before parsing (`src/client.ts:539`), so an answer arriving at all is
* Composio having accepted the request and deleted the account.
*
* READING THAT AS "NO VERDICT" TURNED A COMPLETED WITHDRAWAL INTO A PARTIAL-WITHDRAWAL REFUSAL,
* which leaves the person's connection row standing, tells them their access has not ended, and
* has them press disconnect again — against an account that is already gone, which is a second
* fault waiting on the first. It is the same lie as the unread `success: false` before it, facing
* the other way.
*
* THE OTHER DIRECTION IS ASSERTED NEXT DOOR AND IS NOT WEAKENED BY THIS: `{}` is a document that
* arrived without its verdict, which is a fact about the package, and it still refuses.
*/
for (const { shape, answer } of [
{ shape: "a 204 carrying no content", answer: null },
{ shape: "a JSON reply of content-length zero", answer: undefined },
]) {
test(`a withdrawal Composio answered with ${shape} is a withdrawal`, async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
delete: async (id: string) => {
deleted.push(id);
return answer;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
// And the flag still went out, so the `true` is about a delete that asked for the grant to be
// revoked rather than about one that quietly filed the account away.
expect(deleted).toEqual(["ca_1"]);
});
}
/**
* A ROW THE LISTING NAMED TWICE IS ONE ACCOUNT, NOT TWO.
*
* The paging loop guards against the vendor repeating a CURSOR and not against it repeating a
* ROW, and those are different faults: a page boundary crossed while accounts are being created
* or deleted, or a proxy stitching two overlapping pages together, hands the same id over twice
* with a cursor that advanced perfectly each time. The second delete then meets Composio's "there
* is no such account" — which arrives as a refusal — so a withdrawal that in fact COMPLETED was
* thrown over as a partial one, the person's connection row was left standing, and every retry
* met the same duplicate and failed in the same place.
*
* THE DOUBLE REFUSES THE SECOND DELETE OF ONE ACCOUNT, which is what the vendor does and what
* makes this test able to fail. A stub that answered both identically would be green against an
* adapter that sent the delete twice.
*/
test("an account the listing named twice is withdrawn once", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: accountListing([
{ row: { id: "ca_1" }, page: 1 },
{ row: { id: "ca_1" }, page: 2 },
]).list,
delete: async (id: string) => {
if (deleted.includes(id)) {
throw new Error(
`Composio holds no connected account with the id ${id}.`,
);
}
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
expect(deleted).toEqual(["ca_1"]);
});
/**
* AND THE COUNT IN A REAL PARTIAL FAILURE IS OF ACCOUNTS, NOT OF ROWS.
*
* The denominator was `accounts.length`, which is how many rows the listing handed over — so a
* listing that named one account twice made the sentence a reader is meant to act on state a
* figure nothing had counted. "One of three" over two accounts is the same class of mistake as
* the page-ceiling sentence that asserted a row count it had not measured.
*/
test("a duplicated row is not a third account in the sentence a partial failure carries", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_1" }, { id: "ca_2" }]),
delete: async (id: string) => {
if (id === "ca_2") throw new Error("Composio refused this one.");
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).toMatch(/withdrew 1 of this person's 2 accounts/);
expect(failure.message).not.toMatch(A_CRASH);
});
/**
* AND HOLDING BOTH KINDS OF SURVIVING GRANT IS NOT A REASON TO BE TOLD ABOUT ONE OF THEM.
*
* The two clauses were an `if`/`else if`, so a person holding a nameless account AND a refused one
* read only the dashboard sentence: "disconnecting again meets them unchanged". That is true of
* the nameless row and false of the refused one, and it is the sentence that decides whether they
* press the button again — so the advice that would actually have ended the refused grant was
* suppressed by the presence of a row it says nothing about. `deleteAuthConfig` writes the
* identical pair as two independent `if`s, and the comment over this chain already described both
* remedies as two remedies.
*/
test("a person holding a nameless account and a refused one is told both remedies", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{}, { id: "ca_refused" }]),
delete: refuse("this account's withdrawal"),
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).toMatch(/withdrew 0 of this person's 2 accounts/);
// The row Composio named nothing for, whose only remedy is the dashboard.
expect(failure.message).toMatch(/no id at all/);
// And the one a second press genuinely reaches, which the `else if` was withholding.
expect(failure.message).toMatch(
/Disconnecting again asks only for the accounts that are left\./,
);
expect(failure.message).not.toMatch(A_CRASH);
});
/**
* AND THE SAME SUPPRESSION ONE CONDITION EARLIER, BEFORE A SINGLE ACCOUNT IS LOOKED AT.
*
* The two refusals over the config listing are `ours.length === 0 && held.length > 0` and
* `ours.length === 0 && unreadable.length > 0`, and `held` counts the READABLE rows while
* `unreadable` counts the rest — so both are ordinary facts about one listing and both can be
* true at once. Written as consecutive throws the second is reachable only when the first is
* false, so a person whose app holds one renamed config beside one unreadable row is told that
* "renaming it to end with (OpenBot) lets disconnecting again withdraw them" — which is not true
* while a row nothing could scope the account listing to is still sitting there. The method's own
* partial-withdrawal sentence appends that fact as its own clause; the refusal ahead of it did
* not.
*/
test("a renamed config beside an unreadable one does not promise a disconnect that would finish", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("gmail", [
{ id: "ac_theirs", name: "Gmail", status: "ENABLED" },
{ id: "ac_nameless", status: "ENABLED" },
]),
},
connectedAccounts: {
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).not.toMatch(A_CRASH);
// The renamed-config reading, which this refusal already carried.
expect(failure.message).toMatch(/Composio holds 1 for gmail/);
expect(failure.message).toMatch(/\(OpenBot\)/);
// And the row that was never sorted, which is what makes the rename alone insufficient.
expect(failure.message).toMatch(/cannot read/);
// Nothing was withdrawn either way — the listing was never scoped, so no delete was composed.
expect(deleted).toEqual([]);
});
});
/**
* The three refusals this file authors, and the one thing a route has to be able to do with them.
*
* `routes.ts` answers a thrown broker error by reaching into it for the vendor's own sentence and,
* finding none, telling the reader that Composio said nothing about why and that an administrator
* should check this deployment's key. That advice is wrong for every sentence below: Composio
* answered, this deployment decided, and the remedy is already written down. `brokerSentence` is the
* one seam that tells the two apart, so these assert the recognition rather than the wording.
*/
describe("refusals a route can tell from an outage", () => {
test("an app with no config of ours is recognised as this deployment's own refusal", async () => {
const { broker } = buildComposioClient(
fakeVendor({ authConfigs: { list: async () => ({ items: [] }) } }),
);
const error = await broker
.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/x",
})
.catch((raised: unknown) => raised);
// `/An administrator/` opens two of this method's three refusals, so it recognised the class
// and not the branch. The remedy is what a reader is being handed.
expect(brokerSentence(error)).toMatch(NO_CONFIG_REMEDY);
expect(brokerSentence(error)).not.toMatch(DISABLED_REMEDY);
});
test("a consent with nowhere to send anybody is recognised too", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ id: "ac_ours", name: "Linear (OpenBot)", status: "ENABLED" },
],
}),
},
// An API-key toolkit is connected by typing a secret rather than by visiting a page, so the
// vendor answers with no url. Nothing is wrong with the key, and saying so would be a
// second wrong answer on top of a first.
connectedAccounts: { link: async () => ({ redirectUrl: null }) },
}),
);
const error = await broker
.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: "https://openbot.test/connections/x",
})
.catch((raised: unknown) => raised);
expect(brokerSentence(error)).toMatch(NO_PAGE_REMEDY);
expect(brokerSentence(error)).not.toMatch(NO_CONFIG_REMEDY);
expect(brokerSentence(error)).not.toMatch(DISABLED_REMEDY);
});
});
/**
* What the catalogue is allowed to be, given that it is cached and then believed.
*/
describe("a catalogue that might be a fragment", () => {
/**
* THIS TEST ASSERTED THE OPPOSITE AND WAS CHANGED ON PURPOSE, WHICH IS WORTH READING BEFORE THE
* CODE UNDER IT.
*
* It was "a full page is refused rather than held for ten minutes", and it pinned a refusal whose
* stated reason was that "`LISTING_LIMIT` is the largest page the toolkit endpoint allows and the
* SDK drops the response's cursor, so a catalogue of exactly this size and one larger answer
* identically". The consequence it guarded against is real and is still guarded: a fragment
* committed here is served for ten minutes to the picker AND to the enable route, which then
* tells an administrator that a real app "is not an app Composio lists".
*
* WHAT WAS FALSE WAS THE PREMISE. The cursor exists on the raw client and always did — see the
* paging tests at the end of this file — so the two answers the refusal said were
* indistinguishable are told apart by asking for the next page. And the refusal's cost was not
* hypothetical: Composio publishes more than {@link WHOLE_LISTING} toolkits, so it fired on the
* first call every time and the app picker showed an operator nothing at all.
*
* SO THE ASSERTION IS INVERTED RATHER THAN DELETED, and it is inverted at the same boundary. A
* page of exactly {@link WHOLE_LISTING} rows with a cursor still outstanding is the shape that
* used to be refused; what is asserted now is that the row on the far side of it arrives.
*/
test("a full page is read on from rather than refused", async () => {
let calls = 0;
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async (query: unknown) => {
calls += 1;
return (query as { cursor?: string }).cursor === undefined
? {
items: Array.from({ length: WHOLE_LISTING }, (_, index) => ({
slug: `app_${index}`,
name: `App ${index}`,
meta: {},
})),
next_cursor: "page_2",
}
: {
items: [
{ slug: "the_one_past_the_cut", name: "Past", meta: {} },
],
next_cursor: null,
};
},
},
}),
() => 1_000_000,
);
const apps = await broker.listApps();
expect(calls).toBe(2);
expect(apps).toHaveLength(WHOLE_LISTING + 1);
// The app an administrator would have been told Composio does not publish.
expect(apps.at(-1)?.slug).toBe("the_one_past_the_cut");
});
test("each caller gets its own rows, so one of them cannot edit the cache", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
toolkits: {
list: async () => ({
items: [
{
slug: "gmail",
name: "Gmail",
meta: {
description: "Send and read mail.",
categories: [{ id: "productivity", name: "Productivity" }],
tools_count: 63,
},
},
],
}),
},
}),
() => 1_000_000,
);
const first = await broker.listApps();
first[0].name = "Not Gmail";
first[0].categories.push("Invented");
first.length = 0;
// Nothing does this today, which is exactly why leaving it would be a trap: the first caller
// that sorts or trims the rows would be editing what the next nine minutes of callers read as
// Composio's answer, and the fault would surface in somebody else's request.
const second = await broker.listApps();
expect(second).toEqual([
{
slug: "gmail",
name: "Gmail",
description: "Send and read mail.",
logo: null,
categories: ["Productivity"],
actionCount: 63,
// Composio measures none of the three, so each is an explicit null: "not measured", which is
// a different fact from "measured, and none" and must never be read through a `?? 0`.
classifiedCount: null,
permissionCount: null,
scopedActionCount: null,
connection: NO_SCHEME,
},
]);
});
/**
* AND THE CONNECTION IS A ROW'S SECOND NON-PRIMITIVE, WHICH THE COPY ABOVE WAS NOT MAKING.
*
* The copy spread the row and rebuilt `categories`, on a comment claiming that array was the one
* field here that is not a primitive. `connection` is an object too — see {@link BrokerConnection}
* — so it travelled by reference out of the cache and into every caller for ten minutes, which is
* the exact sharing the copy exists to end. It is also the worst field to share: the app picker
* hides `unsupported` and the enable route branches on `kind` to decide whether to create an auth
* config at all, so a caller that edited the object it was handed would be editing what those two
* decisions read next.
*/
test("each caller gets its own connection, so one of them cannot edit what the picker branches on", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
toolkits: {
list: async () => ({
items: [{ slug: "gmail", name: "Gmail", meta: {} }],
}),
},
}),
() => 1_000_000,
);
const first = await broker.listApps();
const held = first[0].connection;
if (held.kind !== "unsupported") {
throw new Error(`The fixture resolved to ${held.kind}, not unsupported.`);
}
held.reason = "Invented";
const second = await broker.listApps();
expect(second[0].connection).toEqual(NO_SCHEME);
expect(second[0].connection).not.toBe(first[0].connection);
});
});
/**
* WHAT ESCAPES THE SEAM WHEN THE VENDOR THROWS, asked of every method the seam has.
*
* ONE TABLE RATHER THAN A TEST PER DISCOVERY, because the defect this is about has been found four
* times in four methods and each finding was fixed where it was pointed at. `routes.ts` answers a
* thrown broker error by reaching into it for the vendor's own sentence and, finding none, telling
* the reader that Composio said nothing about why and that an administrator should check this
* deployment's Composio key. That is the right thing to say about a socket that hung up and the
* wrong thing to say about every failure the vendor actually explained — and which of the two a
* reader gets is decided by whether the `await vendor.*` that threw happened to sit inside
* something that translates. TypeScript has no checked exceptions, so nothing enumerates the calls
* that do and nothing notices a new one that does not.
*
* THE PROPERTY, STATED ONCE: an error leaving this seam must leave the route something to say —
* either a {@link BrokerRefusalError}, whose sentence this deployment wrote and whose remedy is
* already in it, or a vendor error whose own sentence {@link vendorSentence} can reach. Anything
* else reaches the reader as "check your Composio key", so anything else has to be named below as
* a failure that genuinely deserves that answer.
*
* THE ALLOW-LIST IS ASSERTED IN BOTH DIRECTIONS, which is what stops it becoming a list of
* excuses. An entry on it must actually arrive unexplained; the day a method starts translating
* the failure named there, its entry reddens and has to be deleted rather than quietly outliving
* the state it describes.
*
*/
describe("what a vendor failure becomes on its way out of the seam", () => {
/**
* The two ways a vendor call fails, which are two different questions and not one.
*
* An OUTAGE carries nothing: a socket, a 502 from an edge, a timeout. Nobody wrote a sentence
* about it, so there is none to find and "Composio did not say why" is the honest answer.
*
* A NAMED CONDITION is the opposite case and the one that keeps being missed. `@composio/core`
* raises its own error classes — `ComposioMultipleConnectedAccountsError` and the four others
* down the same door: `ComposioAclOnlyForSharedError`,
* `ComposioFailedToCreateConnectedAccountLink`, `ValidationError`,
* `ComposioRequestCancelledError` — and each one is the vendor saying WHICH condition happened,
* in a message it wrote for a reader. None of it is nested where {@link vendorSentence} looks, so
* a seam that lets one through unexamined converts an explanation into "check the key".
*
* A SHAPE THE SDK ITSELF COULD NOT READ is the third, and it is the one three rounds of review
* wrote guards for at the wrong layer. `@composio/core` 0.18.1 does not hand a malformed listing
* over to be inspected: its own transformers dereference the answer first, so
* `response.items.map(transformAuthConfigRetrieveResponse)` off a bare list, and
* `authConfig.toolkit.logo` off a row that is not an object, raise a bare `TypeError` from inside
* the vendor's code before any reader here is reached (`src/utils/transformers/authConfigs.ts:79`,
* `:41`, and the same two shapes in `connectedAccounts.ts:113`, `:60` and `models/Tools.ts:561`).
* A `TypeError` arriving out of an `await vendor.*` is therefore Composio's shape and not a bug of
* this deployment's, and what it needs is the same thing every other vendor failure needs: a
* sentence.
*/
const THROWN: {
kind: string;
raise: () => Error;
/** What the sentence must say, where the kind of failure settles a remedy. */
demands?: RegExp;
/** What the sentence must not have picked up from the error it translated. */
quiets?: RegExp;
}[] = [
{
kind: "an outage",
raise: () => new Error("socket hang up"),
},
{
kind: "a named vendor condition",
raise: () =>
Object.assign(
new Error(
"Multiple connected accounts found for user user_1 and toolkit linear.",
),
{ name: "ComposioMultipleConnectedAccountsError" },
),
},
{
kind: "a shape the SDK itself could not read",
raise: () =>
new TypeError(
"undefined is not an object (evaluating 'response.items.map')",
),
// One remedy, and it is a package rather than a page: nobody operating this deployment can
// correct what Composio answers, and the key is demonstrably fine — the call went out.
demands: /@composio\/core/,
quiets: A_CRASH,
},
];
type SeamMethod = keyof ComposioBroker | keyof ComposioActions;
/**
* The failures this seam is allowed to hand on unexplained, one entry per state and each with
* its reason written down.
*
* Every one of them is the same claim: the vendor call that failed said nothing this deployment
* could pass on, so "Composio did not answer and an administrator should check the key and their
* status page" is genuinely the best thing a reader can be told. That claim is true of a bare
* `Error` out of a listing and it is NOT true of anything the vendor named.
*/
const GENUINE_OUTAGES: {
method: SeamMethod;
kind: string;
because: string;
}[] = [
{
method: "listApps",
kind: "an outage",
because:
"The catalogue did not answer. There is no app and no person in the question, so the only remedy is the deployment's key or the vendor's status page.",
},
{
method: "ensureAuthConfig",
kind: "an outage",
because:
"Creating the config failed with nothing said. An administrator pressed Add; the app is not enabled, and what to check is the key.",
},
{
method: "authorize",
kind: "an outage",
because:
"Minting the link failed with nothing said. Nobody was sent anywhere and nothing was attached, so trying again is the whole of the advice.",
},
{
method: "grantsFor",
kind: "an outage",
because:
"The account listing did not answer. Nothing is granted or spent by asking what somebody holds, and the page this fills in has the route's own advice — the deployment's key, the vendor's status page — to show instead.",
},
{
method: "isConnected",
kind: "an outage",
because:
"The account listing did not answer. This is a gate rather than a page, and its caller refuses the run either way.",
},
{
method: "accountName",
kind: "an outage",
because:
"The account listing did not answer. There is no name to show either way, and the page this fills in asks nothing more of the vendor than that one listing.",
},
{
method: "connectionFields",
kind: "an outage",
because:
"Reading what the app asks a person for did not answer. No form was drawn and nothing was attached, so there is nothing about this app to say that the route's own advice — the deployment's key, the vendor's status page — does not already cover.",
},
{
method: "revokeAccount",
kind: "an outage",
because:
"The delete did not answer. The vendor's own bare message travels on untouched, naming nothing, because there is nothing else to say: the account may be standing at Composio and this deployment cannot tell whether the request landed. Its caller is undoing its own work rather than a person pressing a button, and what it is owed is the failure itself.",
},
/*
* THE TWO REASONS BELOW USED TO BE FALSE, AND THIS IS THE CASE THE ALLOW-LIST CANNOT CATCH BY
* ITSELF. Its assertion asks whether an AUTHORED sentence reached the reader, so an entry whose
* `because` mis-describes what the reader gets INSTEAD stays green for ever. Both of these said
* the app gets named somewhere downstream; neither does. `listingSentence` returns the thrown
* message verbatim whenever it is neither a schema mismatch nor the vendor's placeholder
* (`./composio`), and `callTool` does the same on the execute path — so "socket hang up" reaches
* an administrator's Plugins page and a model's context exactly like that, bare, naming no app.
* The entries now say so, and the `allowed` branch of the test asserts the message travels
* untouched, which is what makes the claim hold itself up.
*/
{
method: "listActions",
kind: "an outage",
because:
"The action listing did not answer. `./composio`'s `listingSentence` passes the thrown message on verbatim, so the reader gets the vendor's own bare words with no app named — which is all there is, because a listing that did not answer leaves nothing else to say.",
},
{
method: "execute",
kind: "an outage",
because:
"The call itself failed with nothing said. `callTool` passes the thrown message on verbatim unless it is the vendor's placeholder, so the reader gets the vendor's own bare words — the app is named by the connection they pressed, not by this sentence.",
},
];
const UNEXPLAINABLE = new Set(
GENUINE_OUTAGES.map((outage) => `${outage.method}/${outage.kind}`),
);
/**
* The seam methods that REACH NO VENDOR, named here rather than quietly filtered.
*
* `authProviderOf` answers from the shape of Composio itself — a connection is made against an
* auth config and an auth config is per toolkit, so a toolkit IS its own auth provider — and it
* therefore asks nobody anything. A row in the table below would have to invent a vendor call for
* it to break on, which would assert something about the fake and nothing about the method.
*
*/
const DIALS_NOTHING = new Set<SeamMethod>(["authProviderOf"]);
/**
* Every method of the seam, with the vendor call that decides its answer aimed at the throw.
*
* THE CALL THAT DECIDES RATHER THAN THE FIRST ONE. Several of these read a listing before they
* do the thing they are named for, and a vendor whose every method threw would have each of them
* fail at that first read — so the table would be eight tests of one listing and F1, which lives
* behind an auth-config listing that succeeds, would be unreachable. Each entry below answers
* everything on the way in and throws at the step the method exists to perform.
*/
const SEAM_CASES: {
method: SeamMethod;
vendor: (raise: () => Promise<never>) => Parameters<typeof fakeVendor>[0];
ask: (client: ReturnType<typeof buildComposioClient>) => Promise<unknown>;
}[] = [
{
method: "listApps",
vendor: (raise) => ({ toolkits: { list: raise } }),
ask: ({ broker }) => broker.listApps(),
},
{
method: "ensureAuthConfig",
vendor: (raise) => ({
authConfigs: { list: async () => ({ items: [] }), create: raise },
}),
ask: ({ broker }) =>
broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
}),
},
{
method: "deleteAuthConfig",
vendor: (raise) => ({
authConfigs: { list: async () => ({ items: [OURS] }), delete: raise },
}),
ask: ({ broker }) => broker.deleteAuthConfig("linear"),
},
{
method: "authorize",
vendor: (raise) => ({
authConfigs: { list: async () => ({ items: [OURS] }) },
connectedAccounts: { link: raise },
}),
ask: ({ broker }) =>
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
},
{
// The account listing is the first of the three `grantsFor` reads, and the only one a
// failure here can reach: the config listing and the action listing come after it.
method: "grantsFor",
vendor: (raise) => ({ connectedAccounts: { list: raise } }),
ask: ({ broker }) =>
broker.grantsFor({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
},
{
method: "isConnected",
vendor: (raise) => ({ connectedAccounts: { list: raise } }),
ask: ({ broker }) =>
broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
},
{
method: "accountName",
vendor: (raise) => ({ connectedAccounts: { list: raise } }),
ask: ({ broker }) =>
broker.accountName({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
},
{
method: "revoke",
vendor: (raise) => ({
// The configs first, because the withdrawal reads them to find out which accounts are this
// deployment's to end before it asks for any account at all.
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }]),
delete: raise,
},
}),
ask: ({ broker }) =>
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
},
{
method: "connectionFields",
vendor: (raise) => ({ toolkits: { retrieve: raise } }),
ask: ({ broker }) =>
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
},
{
method: "connectWithFields",
vendor: (raise) => ({
// The configs first, for the reason the withdrawal above answers them first: the connection
// is made against this deployment's own config, so the read that finds one has to succeed
// before the create this row is about can be reached at all.
authConfigs: { list: async () => ({ items: [OURS] }) },
connectedAccounts: { create: raise },
}),
ask: ({ broker }) =>
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: "never-sent-anywhere" },
}),
},
{
method: "revokeAccount",
vendor: (raise) => ({ connectedAccounts: { delete: raise } }),
// No listing on the way in, which is the whole shape of this method: the id is what it was
// handed, so the delete is the first vendor call it makes and the only one it can fail at.
ask: ({ broker }) => broker.revokeAccount("ca_new"),
},
{
method: "listActions",
vendor: (raise) => ({ tools: { list: raise } }),
ask: ({ actions }) =>
actions.listActions("gmail", { limit: WHOLE_LISTING }),
},
{
method: "execute",
vendor: (raise) => ({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
toolkit: { slug: "gmail" },
}),
execute: raise,
},
}),
ask: ({ actions }) =>
actions.execute(
{
toolkit: "gmail",
slug: "GMAIL_FETCH_EMAILS",
userId: "user_1",
version: "20260903_00",
},
{},
),
},
];
/**
* The other direction of {@link DIALS_NOTHING}: what is excused from the table must genuinely
* have nothing to fail at. The vendor here has no methods at all, so any call out of this seam
* would raise rather than answer.
*/
test("a method excused from the table reaches no vendor at all", async () => {
const { broker } = buildComposioClient(fakeVendor({}));
expect([...DIALS_NOTHING]).toEqual(["authProviderOf"]);
expect(await broker.authProviderOf("gmail")).toBe("gmail");
});
for (const seamCase of SEAM_CASES) {
for (const thrown of THROWN) {
const allowed = UNEXPLAINABLE.has(`${seamCase.method}/${thrown.kind}`);
test(`${seamCase.method} meeting ${thrown.kind} leaves the route ${
allowed
? "nothing to say, and that is named as an outage"
: "a sentence"
}`, async () => {
const raised = thrown.raise();
const client = buildComposioClient(
fakeVendor(
seamCase.vendor(async () => {
throw raised;
}),
),
() => 1_000_000,
);
const escaped = await failureOf(seamCase.ask(client));
const sentence = brokerSentence(escaped) ?? vendorSentence(escaped);
if (allowed) {
// The allow-list's other direction. This entry claims the reader cannot be told anything
// useful here; the day that stops being true, this line is what says so.
expect(sentence).toBeNull();
/*
* AND WHAT THE READER DOES GET, WHICH IS THE HALF THE `because` COLUMN KEPT GETTING WRONG.
* Two entries above used to claim the reader is left with a named app and only the reason
* missing; the truth is that the vendor's own bare message travels on untouched — through
* `listingSentence` into an app's `lastError`, and through `callTool` into a result — with
* nothing added and no app named. That is what "unexplainable" costs here, so the entries
* say so and this line holds them to it: the day a method starts wrapping the failure, the
* `because` beside it stops being true and this reddens rather than outliving it.
*/
expect(escaped.message).toBe(raised.message);
return;
}
expect(sentence).not.toBeNull();
expect(sentence?.trim()).not.toBe("");
/*
* THE REMEDY IS ASKED OF THE WHOLE FAILURE AND NOT OF ITS FIRST LINE, because two of these
* methods deliberately make a COUNT their sentence. `revoke` and `deleteAuthConfig` are
* withdrawing a SET, and what a reader can act on there is how many of it survived; every
* reason the loop met travels on `cause` instead, which is the only place the detail lives.
* So what has to be true is that the remedy reached the failure somewhere, and reading the
* chain is what says so for both shapes at once.
*/
if (thrown.demands) {
expect(everythingSaidBy(escaped).join("\n")).toMatch(thrown.demands);
}
// The vendor's crash is carried as `cause` and never quoted: a sentence that reads like a
// stack trace is the thing every refusal in this seam was written to stop being.
if (thrown.quiets) expect(sentence).not.toMatch(thrown.quiets);
});
}
}
});
/**
* ONE REMEDY PER VENDOR CONDITION, WHICH IS THE HALF THE TABLE ABOVE CANNOT ASSERT.
*
* That table asks whether a reader is told ANYTHING, and a seam that answered every named condition
* with one sentence would satisfy it completely. This file has already been bitten by exactly that:
* `rejects.toThrow(/linear/)` matched three authored refusals prescribing three different acts by
* three different people, so deleting a whole branch left the suite green. The app name is the part
* every sentence shares; the remedy is the part that makes a sentence worth writing.
*
* SO EACH ROW BELOW IS ASSERTED IN BOTH DIRECTIONS: the sentence a condition produces must carry ITS
* remedy and must carry NO OTHER ROW'S. Two conditions collapsed into one wording fail here twice
* over — the row that lost its remedy, and the row that acquired a second one.
*
* THE CALL SITE OF EACH ROW IS ONE THAT ACTUALLY RAISES IT, read off `@composio/core` 0.18.1 rather
* than chosen for convenience, so a row is also a record of where its condition comes from. The
* table above already establishes that the translation is not call-site-specific; this one
* establishes that the sentences are distinguishable, which is what stops the translation being a
* fallback with a vendor's name on it.
*/
describe("each vendor condition reaches the reader as its own remedy", () => {
/** The vendor's error as it arrives: a name, and a message nothing here reads. */
function raising(name: string): () => Promise<never> {
return async (): Promise<never> => {
throw Object.assign(new Error(`${name} came out of Composio.`), { name });
};
}
/** Minting this person's connect link, which is where three of the rows below come from. */
function whileLinking(raise: () => Promise<never>): Promise<unknown> {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: async () => ({ items: [OURS] }) },
connectedAccounts: { link: raise },
}),
() => 1_000_000,
);
return broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
}
/** Creating this deployment's auth config, where the SDK parses what it is handed. */
function whileCreatingConfig(raise: () => Promise<never>): Promise<unknown> {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: async () => ({ items: [] }), create: raise },
}),
() => 1_000_000,
);
return broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
});
}
/**
* ONE APP ACROSS ALL FOUR CONTEXTS, WHICH IS WHAT MAKES THE CROSS-CHECK BELOW MEAN ANYTHING.
*
* Three of these remedies name the app they are about. The linking and creating contexts were
* about `linear` and the resolving and running ones about `gmail`, so "this sentence does not
* also prescribe somebody else's step" was being asked with a regular expression naming an app
* the sentence could not have mentioned — it passed for every pair that crossed the two contexts
* for a reason that had nothing to do with the sentences, which is most of the table. One app
* makes every row comparable with every other.
*/
const CALL = {
toolkit: "linear",
slug: "LINEAR_CREATE_ISSUE",
userId: "user_1",
version: "20260903_00",
};
/** Resolving the tool before it is run, which is the call that reports a withdrawn action. */
function whileResolving(raise: () => Promise<never>): Promise<unknown> {
const { actions } = buildComposioClient(
fakeVendor({ tools: { getRawComposioToolBySlug: raise } }),
() => 1_000_000,
);
return actions.execute(CALL, {});
}
/** Running it, once the resolve has already agreed about which app it belongs to. */
function whileRunning(raise: () => Promise<never>): Promise<unknown> {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: CALL.slug,
toolkit: { slug: CALL.toolkit },
}),
execute: raise,
},
}),
() => 1_000_000,
);
return actions.execute(CALL, {});
}
const CONDITIONS: {
name: string;
raisedBy: string;
remedy: RegExp;
ask: (raise: () => Promise<never>) => Promise<unknown>;
}[] = [
{
name: "ComposioMultipleConnectedAccountsError",
raisedBy: "connectedAccounts.link",
remedy: /an account this person is already connected through/,
ask: whileLinking,
},
{
name: "ComposioAclOnlyForSharedError",
raisedBy: "connectedAccounts.link",
remedy: /changing how linear is shared in Composio's own dashboard/,
ask: whileLinking,
},
{
name: "ComposioFailedToCreateConnectedAccountLink",
raisedBy: "connectedAccounts.link",
remedy: /no consent was spent/,
ask: whileLinking,
},
{
name: "ValidationError",
raisedBy: "authConfigs.create",
remedy: /upgrading this deployment's @composio\/core/,
ask: whileCreatingConfig,
},
{
name: "ComposioRequestCancelledError",
raisedBy: "tools.execute",
remedy: /asking for it again is what settles/,
ask: whileRunning,
},
{
name: "ComposioConnectedAccountNotFoundError",
raisedBy: "tools.execute",
remedy:
/connecting linear again on this deployment's Connected accounts page/,
ask: whileRunning,
},
{
name: "ComposioToolNotFoundError",
raisedBy: "tools.getRawComposioToolBySlug",
remedy: /records what Composio publishes now/,
ask: whileResolving,
},
{
name: "ComposioToolVersionRequiredError",
raisedBy: "tools.execute",
remedy: /replaces "latest" with a version Composio will accept/,
ask: whileRunning,
},
];
for (const condition of CONDITIONS) {
test(`${condition.name} out of ${condition.raisedBy} prescribes its own step`, async () => {
const failure = await failureOf(condition.ask(raising(condition.name)));
const sentence = brokerSentence(failure) ?? vendorSentence(failure);
expect(sentence).not.toBeNull();
expect(sentence).toMatch(condition.remedy);
// The other direction: a sentence that also prescribes somebody else's step is a sentence two
// conditions are sharing, which is the state this whole table exists to catch.
for (const other of CONDITIONS) {
if (other.name === condition.name) continue;
expect(sentence).not.toMatch(other.remedy);
}
});
}
test("an account Composio no longer holds is raised as its own class, so a call can offer Reconnect", async () => {
const failure = await failureOf(
whileRunning(raising("ComposioConnectedAccountNotFoundError")),
);
expect(failure).toBeInstanceOf(BrokerAccountGoneError);
// Still an authored refusal, so every reader that prefers this deployment's sentence still does.
expect(failure).toBeInstanceOf(BrokerRefusalError);
// And nothing else is: the class is what the store acts on.
const other = await failureOf(
whileRunning(raising("ComposioRequestCancelledError")),
);
expect(other).not.toBeInstanceOf(BrokerAccountGoneError);
});
/**
* ONE VENDOR CLASS OVER EVERY WAY A FETCH CAN FAIL, which is a fact about the SDK rather than a
* reading of its name. `getRawComposioToolBySlug` wraps its retrieve in a try whose catch
* rethrows everything except a cancellation as `ComposioToolNotFoundError` (`@composio/core`
* 0.18.1, `src/models/Tools.ts:709-721`), and `tools.execute` resolves through that same method
* (`:1163`). A 500, a 429, a refused key and a socket that hung up therefore all arrive wearing
* the name of an action that was withdrawn — and the sentence read the name as the finding,
* telling an administrator during an outage that Composio no longer publishes their action and
* that pressing Refresh at the vendor that is not answering will fix it.
*/
test("the withdrawn-action condition does not claim to know Composio withdrew anything", async () => {
const failure = await failureOf(
whileResolving(raising("ComposioToolNotFoundError")),
);
const sentence = brokerSentence(failure);
expect(sentence).not.toBeNull();
// The refresh stays, because a withdrawn action is the commonest of them and the refresh is
// the only act that settles that reading.
expect(sentence).toMatch(/records what Composio publishes now/);
// What was missing is the other reading, and the fact that separates the two — which is
// something an administrator can go and look at.
expect(sentence).toMatch(
/a timeout, a dropped connection, a 500, a refused key/,
);
expect(sentence).toMatch(/says nothing that tells the two apart/);
// And the claim it must no longer make.
expect(sentence).not.toMatch(/no longer publishes that action/);
});
/**
* The vendor's own words win where there are any, which is the limit on translating at all.
*
* `routes.ts` reads {@link brokerSentence} first and {@link vendorSentence} second, so a refusal
* authored here HIDES whatever Composio's own server said. Several of the SDK's classes are
* wrappers that carry the server's explanation underneath — `ComposioFailedToCreateConnectedAccountLink`
* is one, and it is on the table above — so translating one of those unconditionally would replace
* a specific server message with this deployment's general one. Where the vendor explained itself,
* the error is passed on untouched and the reader gets the vendor's sentence.
*/
test("a condition whose vendor message is reachable is passed on rather than reworded", async () => {
const failure = await failureOf(
whileLinking(async (): Promise<never> => {
throw Object.assign(
new Error("Failed to create connected account link"),
{
name: "ComposioFailedToCreateConnectedAccountLink",
cause: {
error: {
error: {
message:
"The auth config linear (OpenBot) has no redirect URI registered.",
},
},
},
},
);
}),
);
expect(brokerSentence(failure)).toBeNull();
expect(vendorSentence(failure)).toBe(
"The auth config linear (OpenBot) has no redirect URI registered.",
);
});
});
/**
* WHAT THE LOOP THAT DELETES A SET OF THINGS DOES WITH WHAT IT CATCHES.
*
* `deleteAuthConfig` and `revoke` each ask Composio to end several objects that independently hold
* somebody's access, and both attempt all of them rather than stopping at the first refusal — which
* is the right shape and was reporting almost none of what it learned. Two things were wrong with
* it, and they are different failures rather than one.
*
* EVERY REASON AFTER THE FIRST WAS DISCARDED. The throw carried `cause: refused[0]` and nothing
* else, so a person with five accounts of which three refused left one reason behind and two gone —
* and the sentence a reader gets is a count, deliberately, so the reasons were the only place the
* detail lived at all.
*
* AND A BUG OF OURS WAS COUNTED AS A REFUSAL BY COMPOSIO. The catch took everything, so a
* `TypeError` out of this adapter's own code became one more "Composio refused the rest" — a
* sentence telling an operator to press disconnect again, about a fault that will do the same thing
* every time and that no amount of retrying reaches.
*/
describe("what the delete loop keeps of the failures it meets", () => {
test("every account Composio refused is carried, not only the first", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_2" }, { id: "ca_3" }]),
delete: async (id: string) => {
if (id !== "ca_1") throw new Error(`Composio refused ${id}.`);
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// The sentence stays the count, which is what a reader can act on. The reasons are what a log
// reader needs, and there are two of them.
expect(brokerSentence(failure)).toMatch(/1 of this person's 3 accounts/);
const cause = failure.cause;
expect(cause).toBeInstanceOf(AggregateError);
expect(
(cause as AggregateError).errors.map((one) => (one as Error).message),
).toEqual(["Composio refused ca_2.", "Composio refused ca_3."]);
});
test("a single refusal is still carried as itself rather than wrapped", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_2" }]),
delete: async (id: string) => {
if (id === "ca_2") throw new Error("Composio refused that one.");
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect((failure.cause as Error).message).toBe("Composio refused that one.");
});
/**
* A `TypeError` OUT OF A VENDOR CALL IS COMPOSIO'S SHAPE, AND THIS TEST USED TO ASSERT THE REVERSE.
*
* It was written around `isOurFault`, whose premise was that a `TypeError` is what a mistake in
* this file looks like and never something "Composio can reply". Running `@composio/core` 0.18.1
* falsifies that premise outright: a bare list where `{ items }` belongs, an envelope whose
* `items` is a string, and a row that is not an object all raise a bare `TypeError` from inside
* the vendor's own transformers, before any code here is reached. So the classification was
* inverted — a vendor fault escaped the loop as a bug of ours, abandoning every account after it
* unasked, and the reader was told nothing at all.
*
* WHICH IS WHY THE GUARD MOVED RATHER THAN BEING RETUNED. `askVendor` wraps the `await vendor.*`
* and nothing else, so "the fault surfaced inside the vendor's code" is a fact about the call
* stack there rather than a guess from an error class; the loop no longer has to tell the two
* apart, because by the time an error reaches it the question has been answered one layer down.
*/
test("a shape the SDK could not read is Composio refusing, and the loop goes on", async () => {
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: "ca_1" }, { id: "ca_2" }, { id: "ca_3" }]),
delete: async (id: string) => {
if (id === "ca_2") {
throw new TypeError(
"undefined is not an object (evaluating 'x')",
);
}
deleted.push(id);
return WITHDRAWN;
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// The third account is the one the old classification abandoned: a `TypeError` at the second
// escaped the loop, so a live grant was never asked about and nothing in the answer said so.
expect(deleted).toEqual(["ca_1", "ca_3"]);
expect(brokerSentence(failure)).toMatch(/2 of this person's 3 accounts/);
// And the crash is carried rather than quoted: the sentence a person reads is this
// deployment's, and the vendor's own words are on `cause` for whoever is reading a log.
expect(failure.message).not.toMatch(A_CRASH);
expect((failure.cause as Error).cause).toBeInstanceOf(TypeError);
});
test("the same two promises hold for the loop that removes an app's configs", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [OURS, OURS_SPARE]),
delete: async (id: string) => {
throw new Error(`Composio refused ${id}.`);
},
},
}),
() => 1_000_000,
);
const failure = await failureOf(broker.deleteAuthConfig("linear"));
expect(brokerSentence(failure)).toMatch(
/0 of this deployment's 2 authorization configs/,
);
expect(
(failure.cause as AggregateError).errors.map(
(one) => (one as Error).message,
),
).toEqual(["Composio refused ac_ours.", "Composio refused ac_ours_spare."]);
});
});
/**
* WHAT EACH VENDOR LISTING IS ALLOWED TO BE, given that this file's types only assert its shape.
*
* A TYPESCRIPT INTERFACE OVER A WIRE VALUE IS AN ASSERTION AND NOT A CHECK, which is the reason
* this table exists — but only for the fields, and that distinction is the whole of what a round of
* running `@composio/core` 0.18.1 established. Three of these four listings go through the SDK's
* warn-only `transform()`, which logs a `safeParse` failure and returns the unvalidated object, so a
* toolkit whose name is null, an auth config whose id is missing and a connected account with no id
* all arrive here exactly as they came off the wire. Those are the shapes below, and each one was
* OBSERVED arriving rather than reasoned about.
*
* WHAT IS NOT BELOW ANY MORE IS THE CONTAINER, AND THAT IS A CORRECTION RATHER THAN A GAP. This
* table used to open each listing with "nothing at all" and "a bare list where an envelope belongs",
* on the claim that those had been observed too. They had not, and they cannot be: every one of the
* SDK's list transformers dereferences the answer before returning it — `response.items.map(...)`
* for the two paged listings and for the tool list, `item.meta.categories` for the catalogue — so a
* container of the wrong shape dies inside the vendor's code, as a bare `TypeError` on three paths
* and as `ComposioToolkitFetchError` on the catalogue, before any reader in the adapter is reached.
* That failure is a vendor-shape fault and is answered as one, which is asserted next door in the
* seam table rather than pretended at here.
*
* WHAT A MALFORMED ANSWER MUST NOT BECOME IS A CRASH REPORT. `f.toLowerCase is not a function` and
* `null is not an object` are what these produce without a reader: the first as an unhandled 500 on
* a live route, the rest as a 502 telling an administrator to check a key that is perfectly good. So
* each case asserts that the call refuses, and that the refusal is a sentence rather than the name
* of a method that was not there.
*
* ASSERTED AS A PROPERTY AND NOT AS A WORDING, because what is required is that a reader be told
* something, and that nothing be sent to the vendor on the strength of a field the answer did not
* carry. The second half is the one that had rotted: `sent` was a literal empty array in half these
* cases and no stub ever wrote to it, so the assertion holding it was a tautology dressed as a
* check. It is now every vendor call the adapter made, in order, and each listing says which single
* call that should be.
*/
describe("a vendor listing that is not the shape it is declared to be", () => {
/** Every vendor method the adapter reached, named, in the order it was called. */
type Probe = {
parts: Parameters<typeof fakeVendor>[0];
sent: string[];
};
const MALFORMED_LISTINGS: {
listing: string;
answers: { shape: string; answer: unknown }[];
probe: (answer: unknown) => Probe;
/** The one call this listing's fault is allowed to have made before it refused. */
asked: string[];
ask: (client: ReturnType<typeof buildComposioClient>) => Promise<unknown>;
/** Whether the refusal has to be one a route passes through as this deployment's own. */
authored: boolean;
}[] = [
{
listing: "the app catalogue",
answers: [
{
shape: "a row whose slug is null",
answer: { items: [{ slug: null, name: "Gmail", meta: {} }] },
},
{
shape: "a row whose name is null",
answer: { items: [{ slug: "gmail", name: null, meta: {} }] },
},
{
shape: "a category the vendor named with nothing",
answer: {
items: [
{ slug: "gmail", name: "Gmail", meta: { categories: [{}] } },
],
},
},
],
probe: (answer) => {
const sent: string[] = [];
return {
parts: {
toolkits: {
list: async () => {
sent.push("toolkits.get");
return answer;
},
},
},
sent,
};
},
asked: ["toolkits.get"],
ask: ({ broker }) => broker.listApps(),
authored: true,
},
{
listing: "this app's auth configs",
answers: [
{
shape: "a row with no name",
answer: { items: [{ id: "ac_ours", status: "ENABLED" }] },
},
{
shape: "a row whose id is null",
answer: {
items: [{ id: null, name: "Linear (OpenBot)", status: "ENABLED" }],
},
},
],
probe: (answer) => {
const sent: string[] = [];
return {
parts: {
authConfigs: {
list: async () => {
sent.push("authConfigs.list");
return answer;
},
},
connectedAccounts: {
link: async () => {
sent.push("connectedAccounts.link");
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
},
sent,
};
},
asked: ["authConfigs.list"],
ask: ({ broker }) =>
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
authored: true,
},
{
listing: "this person's accounts",
answers: [
{ shape: "a row with no id", answer: { items: [{}] } },
{ shape: "a row whose id is null", answer: { items: [{ id: null }] } },
{ shape: "a row whose id is a number", answer: { items: [{ id: 7 }] } },
],
probe: (answer) => {
const sent: string[] = [];
return {
parts: {
authConfigs: {
list: async () => {
sent.push("authConfigs.list");
return { items: [OUR_GMAIL] };
},
},
connectedAccounts: {
list: async () => {
sent.push("connectedAccounts.list");
return answer;
},
delete: async () => {
sent.push("connectedAccounts.delete");
},
},
},
sent,
};
},
// The whole listing is unreadable here, so there is no readable grant to withdraw and the
// delete must not be reached at all — a withdrawal of `undefined` is the request this refusal
// exists to stop being made. Where SOME rows are readable the answer is different and the
// test for it sits beside `revoke`: those go, and the sentence counts what was left.
//
// The config listing goes out first because the withdrawal is scoped to this deployment's own
// configs before it asks for an account at all; it is named here rather than left out so that
// the assertion stays a statement about the whole conversation with the vendor.
asked: ["authConfigs.list", "connectedAccounts.list"],
ask: ({ broker }) =>
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
authored: true,
},
{
listing: "this app's actions",
answers: [
// The one row fault `ToolSchema` admits: `z.string()` is satisfied by the empty string, and
// an action's slug is `mcp_tools.name` — NOT NULL and half the primary key — as well as
// what a later call sends back to Composio.
{
shape: "an action whose slug is empty",
answer: { items: [{ slug: "", name: "Fetch emails" }] },
},
],
probe: (answer) => {
const sent: string[] = [];
return {
parts: {
tools: {
list: async () => {
sent.push("tools.getRawComposioTools");
return answer;
},
},
},
sent,
};
},
asked: ["tools.getRawComposioTools"],
ask: ({ actions }) =>
actions.listActions("gmail", { limit: WHOLE_LISTING }),
// `./composio` authors this one's sentence, not `./broker`: a listing failure is recorded in
// the app's `lastError` rather than answered to a route, so what is required here is a
// sentence and not a class.
authored: false,
},
];
for (const listing of MALFORMED_LISTINGS) {
for (const { shape, answer } of listing.answers) {
test(`${listing.listing} answered with ${shape} is refused in a sentence`, async () => {
const probe = listing.probe(answer);
const client = buildComposioClient(
fakeVendor(probe.parts),
() => 1_000_000,
);
const failure = await failureOf(listing.ask(client));
expect(failure.message).not.toMatch(A_CRASH);
expect(failure.message.trim()).not.toBe("");
// THE ROW READER ANSWERED AND NOT THE CONTAINER GUARD, which is the whole of what each of
// these cases is named after. Every answer above is a well-formed envelope carrying ONE bad
// row, so `pageOf`'s "what came back is not a listing at all" must not be the sentence:
// that sentence means the fixture never reached the slug, name, category or id reader whose
// fault the test claims to be about, and it is the exact way these tests rotted before —
// three catalogue answers and the action answer were bare arrays, every one of them refused
// at the envelope, and all four passed on the strength of a refusal they had not asked for.
expect(failure.message).not.toMatch(NOT_A_LISTING);
if (listing.authored) {
expect(brokerSentence(failure)).not.toBeNull();
}
// Nothing was sent to the vendor on the strength of a field the answer did not carry: an
// id-less account reaching the delete is a request to withdraw `undefined`, which the
// vendor is free to read as anything at all. The listing itself is what SHOULD have gone
// out, so the assertion names it rather than asking for silence — an adapter that stopped
// asking at all would satisfy an empty expectation perfectly.
expect(probe.sent).toEqual(listing.asked);
});
}
}
});
/**
* A listing that came back at the page ceiling, and what a caller may conclude from it.
*
* THE TWO LISTINGS HERE CARRY A CURSOR AND THE CATALOGUE DOES NOT, which is why they are answered
* differently from the fragment refusal next door. `AuthConfigListParamsSchema` and
* `ConnectedAccountListParamsSchema` both name a `cursor` (`@composio/core` 0.18.1,
* `src/types/authConfigs.types.ts:124-131` and `src/types/connectedAccounts.types.ts:259-266`),
* both models forward it (`src/models/AuthConfigs.ts:95`, `src/models/ConnectedAccounts.ts:118`),
* and both transformers fill `nextCursor` in from the response
* (`src/utils/transformers/authConfigs.ts:80`, `connectedAccounts.ts:116`). The toolkit listing has
* none of that — its response is a bare array with the cursor dropped before any caller sees it —
* so there the only honest answer is to refuse, and here it is to go and read the rest.
*
* WHAT IS ACTUALLY BEING PROTECTED IS `revoke`'s `true`. It means "this person's access has ended",
* and `store.ts` writes that into the audit trail and then deletes the one row naming which app they
* had connected. One page of their accounts is not the set of their accounts, so the assertions
* below are on WHAT WENT OUT — every account, from every page — rather than on what came back: an
* implementation that read one page answers `true` just as confidently.
*/
describe("a listing that arrived with a cursor still outstanding", () => {
/** The statuses the revoke asks about, spelled once for the two queries asserted below. */
const REVOCABLE_STATUSES = [
"INITIALIZING",
"INITIATED",
"ACTIVE",
"FAILED",
"EXPIRED",
"INACTIVE",
];
test("every page of this person's accounts is read, and every account on them withdrawn", async () => {
const deleted: string[] = [];
const { list, asked } = accountListing([
{ row: { id: "ca_1" }, page: 1 },
{ row: { id: "ca_2" }, page: 2 },
]);
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list,
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
// `ca_2` is the whole test. It is on the second page, so a reader that stopped at the first
// deletes `ca_1`, answers `true`, and leaves a live grant behind an audit row saying this
// person's access ended.
expect(deleted).toEqual(["ca_1", "ca_2"]);
// The first request carries no cursor at all, and the second carries the vendor's own word for
// where it left off — which is the half a reader cannot infer from the rows that came back.
expect(asked).toEqual([
{
userIds: [VENDOR_USER],
toolkitSlugs: ["gmail"],
statuses: REVOCABLE_STATUSES,
accountType: "ALL",
authConfigIds: [OUR_GMAIL.id],
limit: WHOLE_LISTING,
},
{
userIds: [VENDOR_USER],
toolkitSlugs: ["gmail"],
statuses: REVOCABLE_STATUSES,
accountType: "ALL",
authConfigIds: [OUR_GMAIL.id],
limit: WHOLE_LISTING,
cursor: "page_2",
},
]);
});
test("an account on a later page still decides whether somebody is connected", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
// Page one holds only the accounts this question must leave out.
list: accountListing([{ row: { id: "ca_2" }, page: 2 }]).list,
},
}),
);
// A first page that is empty with a cursor still outstanding is exactly the shape that reads as
// "this person has no account", which then tells them to connect an app they already hold — and
// tells the gate in `./access` that they may not act through one they can.
expect(
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
});
/**
* A YES/NO QUESTION THAT PAGING MADE FAILABLE, WHICH IS THE OTHER HALF OF THE TEST ABOVE.
*
* Reading every page is what makes `isConnected`'s `false` honest, and it is also what put the
* two cursor refusals and the page ceiling in front of a person whose ACTIVE account had already
* been found. `true` is settled the moment one row arrives — no cursor Composio sends next and no
* fiftieth page can turn it into anything else — so a fault on a page nobody needed was deciding
* the answer to a question nobody still had. And the consequence is not a wasted request:
* `store.ts` DELETES this person's `composio_connections` row on anything other than a `true`,
* and the route turns the refusal into "Composio's answer could not be read" over an account that
* is right there on page one.
*
* THE THREE FAULTS ARE ASSERTED SEPARATELY, because they are three different branches of
* `everyRowOf` and an early stop that closed one of them would be green on a test that only asked
* about another.
*/
for (const { fault, pages } of [
{
fault: "a cursor that is not a cursor",
pages: () => async () => ({ items: [{ id: "ca_1" }], nextCursor: 7 }),
},
{
fault: "a cursor that never advances",
pages: () => async () => ({
items: [{ id: "ca_1" }],
nextCursor: "page_2",
}),
},
{
fault: "a cursor that advances for ever",
pages: () => {
let page = 0;
return async () => ({
items: [{ id: `ca_${++page}` }],
nextCursor: `page_${page + 1}`,
});
},
},
]) {
test(`${fault} cannot unanswer a connection the first page proved`, async () => {
let asked = 0;
const page = pages();
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
list: async () => {
asked += 1;
return page();
},
},
}),
() => 1_000_000,
);
expect(
await broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
// One request, because the first answer settled it. Counted rather than left implicit: an
// implementation that read on and happened not to throw would answer `true` as well, and the
// whole point is that the later pages are never reached.
expect(asked).toBe(1);
});
}
/**
* AND THE `false` IS STILL NOT ALLOWED TO BE A GUESS, which is what stops the fix above from
* collapsing into "read one page and answer".
*
* With no row in hand the question is genuinely unsettled, so a cursor this deployment cannot
* follow means it does not know — and saying `false` there would delete the person's row and tell
* a gate they may not act through an app they hold. The refusal is the honest answer, and it is
* the one an early stop is most likely to take away by accident.
*/
test("a cursor fault before any account has been seen is still a refusal", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
list: async () => ({ items: [], nextCursor: 7 }),
},
}),
() => 1_000_000,
);
const failure = await failureOf(
broker.isConnected({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
expect(failure).toBeInstanceOf(BrokerRefusalError);
expect(failure.message).not.toMatch(A_CRASH);
});
test("every page of this app's configs is read, so none is left standing", async () => {
const asked: unknown[] = [];
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async (query: unknown) => {
asked.push(query);
return (query as { cursor?: string }).cursor === undefined
? { items: [OURS], nextCursor: "page_2" }
: { items: [OURS_SPARE], nextCursor: null };
},
delete: async (id: string) => {
deleted.push(id);
},
},
}),
);
await broker.deleteAuthConfig("linear");
// The spare from a lost enable race is on page two. Left behind, it is a config the removal was
// supposed to drop, holding every grant made against it, with the app's row deleted after this
// returns and nothing left in this deployment pointing at it.
expect(deleted).toEqual(["ac_ours", "ac_ours_spare"]);
expect(asked).toEqual([
{ toolkit: "linear", limit: WHOLE_LISTING, showDisabled: true },
{
toolkit: "linear",
limit: WHOLE_LISTING,
showDisabled: true,
cursor: "page_2",
},
]);
});
test("a config of ours on a later page is the one a connection is begun against", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async (query: unknown) =>
(query as { cursor?: string }).cursor === undefined
? { items: [BY_HAND], nextCursor: "page_2" }
: { items: [OURS], nextCursor: null },
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
// Reading one page here answers "this deployment has no config for linear" and sends an
// administrator to remove and re-add an app whose config is sitting on page two.
expect(linked).toEqual([
[VENDOR_USER, "ac_ours", { callbackUrl: RETURN_URL }],
]);
});
test("a cursor that is not a cursor is refused rather than read as the end of the list", async () => {
let calls = 0;
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: async () => {
calls += 1;
return { items: [{ id: "ca_1" }], nextCursor: 42 };
},
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// Read as absent, a cursor this deployment cannot follow is a truncated page wearing the
// clothes of a complete answer — which is the one thing this guard exists to make impossible.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(deleted).toEqual([]);
/*
* THE REFUSAL HAS TO BE THIS ONE AND NOT THE LOOP GUARD NEXT DOOR, which is what these two
* assertions are for and what a mutation run proved they had to be. Coerce the unreadable
* cursor to "" and the paging sends a SECOND request carrying it, gets the same page back, and
* refuses — with a sentence saying Composio answered the same page twice, which is a complaint
* about the vendor for something this deployment did. One request went out, and the sentence
* names what arrived where a cursor belongs.
*/
expect(calls).toBe(1);
expect(refusal.message).toMatch(/where the cursor to the next page/);
});
/**
* A CURSOR WITH NOTHING IN IT IS THE END OF THE LISTING, NOT A REFUSAL — AND THE VENDOR'S OWN
* TYPES PERMIT IT.
*
* All four list responses in the installed client declare `next_cursor?: string | null`
* (`@composio/client` 0.1.0-alpha.76, `resources/auth-configs.d.ts:248`,
* `connected-accounts.d.ts:4987`, `toolkits.d.ts:326`, `tools.d.ts:204`), so `""` is type-legal
* on the wire; both transformers write `response.next_cursor ?? null`, which does not catch it;
* and it therefore reached the guard and became a hard refusal. What that refusal takes down is
* not one call: `revoke`, `authorize`, `ensureAuthConfig`, `deleteAuthConfig` and `isConnected`
* all read one of these two listings, so every app in the deployment stops working at once, for
* as long as the vendor sends it — over a field whose whole content is that it has none.
*
* AND THERE IS NO SECOND REQUEST IT COULD HAVE MEANT. An empty cursor is exactly what this loop
* sends when it has no position: the first request omits the field. Following it asks for page
* one again, which is why the alternative reading ends in the loop guard next door accusing
* Composio of answering the same page twice — a complaint about the vendor for something this
* deployment did.
*
* THE ASSERTION IS ON WHAT WENT OUT AS WELL AS ON WHAT CAME BACK. An implementation that read the
* empty cursor as the end and ALSO sent a second request would answer identically here without
* the call count, and it is the second request that is the defect.
*/
for (const { shape, cursor } of [
{ shape: "an empty string", cursor: "" },
{ shape: "a string of blank space", cursor: " " },
]) {
test(`a cursor Composio sent as ${shape} ends the listing rather than refusing it`, async () => {
let calls = 0;
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: async () => {
calls += 1;
return { items: [{ id: "ca_1" }], nextCursor: cursor };
},
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
expect(deleted).toEqual(["ca_1"]);
expect(calls).toBe(1);
});
}
/**
* AND THE SAME ON THE CONFIG LISTING, WHICH IS THE HALF THIS FILE KEEPS FORGETTING.
*
* One cursor guard serves both listings, so a fix written against the accounts path is a fix
* everywhere — and a test written only against the accounts path is a test that cannot tell the
* difference. Removing an app reads this listing and nothing else, so an empty cursor refused
* here is an app nobody can withdraw.
*/
test("an empty cursor ends the config listing too, so the app can still be removed", async () => {
let calls = 0;
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => {
calls += 1;
return { items: [OURS], nextCursor: "" };
},
delete: async (id: string) => {
deleted.push(id);
},
},
}),
);
await broker.deleteAuthConfig("linear");
expect(deleted).toEqual(["ac_ours"]);
expect(calls).toBe(1);
});
test("a cursor that never advances is refused rather than followed for ever", async () => {
let calls = 0;
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: async () => {
calls += 1;
if (calls > 20) throw new Error("The paging did not terminate.");
return { items: [{ id: "ca_1" }], nextCursor: "page_2" };
},
// The delete ANSWERS rather than refusing, which is what makes this test able to fail: a
// reader that follows no cursor withdraws `ca_1`, reports a completed disconnection, and
// would satisfy any assertion that only asked for a refusal of some kind.
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// A vendor answering the same cursor for ever is a hung request rather than a long one, and the
// caller here is a person waiting on a page they pressed disconnect from.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// EXACTLY TWO, AND `toBeLessThanOrEqual(3)` WAS THE SLACK THAT PINNED NOTHING. The first
// request carries no cursor; the second carries `page_2`; the third would carry `page_2` again,
// which is the repetition the guard exists to catch — so it is refused before it is made and
// two is the only count this guard can produce. A bound of three was green over a guard that
// allowed one repeat before refusing, which is a guard that has stopped answering the question
// "did following the cursor advance". It also read as an assertion about the CEILING, which is
// the other test, and which stops at 200.
expect(calls).toBe(2);
expect(deleted).toEqual([]);
});
test("a cursor that advances for ever is stopped at a ceiling, and stopping is a refusal", async () => {
let calls = 0;
const deleted: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: async () => {
calls += 1;
// A cursor that is different every time defeats the same-page guard above, so this is
// the one shape only the ceiling catches. The throw is the test's own stop: without a
// ceiling in the adapter this listing has no end at all.
if (calls > 200) throw new Error("The paging did not terminate.");
// One row a page, so the row count in the refusal is a figure somebody counted rather
// than the page size this deployment asked for.
return {
items: [{ id: `ca_${calls}` }],
nextCursor: `page_${calls}`,
};
},
delete: async (id: string) => {
deleted.push(id);
return WITHDRAWN;
},
},
}),
);
const refusal = await failureOf(
broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
);
// Stopping is the easy half; the half that matters is that stopping is not answering. A ceiling
// that returned the rows it had would be the page ceiling again, further out and harder to see.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(deleted).toEqual([]);
// The number of pages that happened, and the number the sentence states, are the same number.
expect(calls).toBe(PAGES_BEFORE_REFUSING);
expect(refusal.message).toMatch(
new RegExp(`answered ${PAGES_BEFORE_REFUSING} pages`),
);
// And the sentence asserts no page size nobody measured. `at 1000 rows each` was the limit this
// deployment ASKED for, stated as a fact about what Composio sent — these pages carry one row.
expect(refusal.message).not.toMatch(new RegExp(`${WHOLE_LISTING} rows`));
expect(refusal.message).toMatch(
new RegExp(`${PAGES_BEFORE_REFUSING} rows in all`),
);
});
});
/**
* The two vendor answers that are single objects, and what is actually in doubt about each.
*
* THE CONTAINER IS NOT, WHICH IS A CORRECTION TO WHAT THESE USED TO ASSERT. Both answers were once
* fed a bare `null` on the argument that a single object read straight off an `await` has a declared
* type that only looks settled. Running `@composio/core` 0.18.1 settles it for real, on both paths
* and for different reasons: `getRawComposioToolBySlug` ends in a throwing `ToolSchema.parse`
* (`src/models/Tools.ts:719`), and `connectedAccounts.link` builds its answer with
* `createConnectionRequest(...)` inside a try that turns everything else into
* `ComposioFailedToCreateConnectedAccountLink` (`src/models/ConnectedAccounts.ts:420-453`). So
* neither can hand over something that is not an object, and the refusals that stood for that were
* branches no answer could reach.
*
* WHAT IS IN DOUBT IS EACH ONE'S ONE COPIED FIELD. The tool's `toolkit.slug` is a required string
* that `z.string()` lets be empty, and the request's `redirectUrl` is `response.redirect_url`
* carried across untouched by a builder that validates nothing. Those are what these tests are
* about now, and both are shapes Composio can actually send.
*/
describe("a vendor answer that is one object rather than a listing", () => {
/** The call `execute` is made with in this section, which is a mismatch test's whole setup. */
const GMAIL_CALL = {
slug: "GMAIL_FETCH_EMAILS",
toolkit: "gmail",
userId: "user_1",
version: "20260903_00",
};
/**
* A RESOLVE THAT FAILED IS A CALL THAT MUST NOT RUN, WHICH IS THE HALF WORTH KEEPING.
*
* This test used to hand the resolve a bare `null` and assert that reading a field off it was
* refused rather than crashed. `@composio/core` 0.18.1 cannot answer that: `getRawComposioToolBySlug`
* ends in `transformToolCases`, whose last act is a throwing `ToolSchema.parse`
* (`src/models/Tools.ts:719`, `:193`), so a null answer raises `TypeError: null is not an object
* (evaluating 'tool.input_parameters')` and anything else that is not a tool raises a `ZodError` —
* neither of which reaches a reader in the adapter. The guard it covered is gone; the property
* underneath it is not, and this is that property asked of an input the vendor can actually
* produce.
*/
test("a resolve the SDK could not read refuses, and nothing is run", async () => {
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => {
throw new TypeError(
"null is not an object (evaluating 'tool.input_parameters')",
);
},
execute: async (...call: unknown[]) => {
ran.push(call);
return { successful: true, data: {} };
},
},
}),
);
const refusal = await failureOf(actions.execute(GMAIL_CALL, {}));
// `./composio` puts whatever comes out of here into a model's context and an audit row, so the
// crash is carried rather than quoted and the sentence names the one act that changes anything.
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/GMAIL_FETCH_EMAILS/);
expect(refusal.message).toMatch(/@composio\/core/);
expect(ran).toEqual([]);
});
test("an app the vendor named with nothing is not reported as no app at all", async () => {
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
// The one toolkit fault a passing `ToolSchema.parse` still admits: `ToolkitSchema`
// spells the slug required and `z.string()` is satisfied by the empty string. A bare
// string where `{ slug }` belongs — what this fixture used to be — raises a `ZodError`
// inside the SDK and never arrives.
toolkit: { slug: "", name: "Gmail" },
}),
execute: async (...call: unknown[]) => {
ran.push(call);
return { successful: true, data: {} };
},
},
}),
);
const refusal = await failureOf(actions.execute(GMAIL_CALL, {}));
/*
* THE TWO FACTS ARE NOT THE SAME AND THEIR REMEDIES ARE NOT EITHER. "Composio resolves that
* action to no app at all" is a statement about the action, and the sentence carrying it tells
* an administrator to refresh the app's tools — right for a slug recorded against a url that
* has since changed, and useless for an SDK that has begun answering a different shape. The
* toolkit here is PRESENT and its name is blank, which is neither of those.
*/
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).not.toMatch(/no app at all/);
expect(ran).toEqual([]);
});
test("an action resolved with a null app is refused rather than crashed over", async () => {
/*
* THE SAME `undefined`-ONLY EXEMPTION AS THE THREE FIELD GUARDS IN {@link actionOf}, ONE CALL
* OVER, AND IT FAILS HARDER. "Composio named no app for this action" is a state this block
* already has a sentence for — `ran ?? "no app at all"` — so absence is an answer here; `null`
* is the wire's other spelling of it, and `answeredApp !== undefined` read it as PRESENT and
* then took `.slug` off it. That is a bare "null is not an object" thrown from outside every
* vendor `try` in the adapter, which is the one outcome this file's sentences may never become:
* `./composio` puts what comes out of `execute` into a model's context and an audit row.
*
* NOTHING IS RUN EITHER WAY, WHICH IS THE HALF THAT WAS NEVER IN DOUBT AND IS ASSERTED ANYWAY.
* The refusal exists because the gate in `./access` cleared this run against the app the
* connection names, and an action the vendor attributes to nothing cannot be shown to be that
* app.
*/
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
name: "Fetch emails",
toolkit: null,
}),
execute: async (...call: unknown[]) => {
ran.push(call);
return { successful: true, data: {} };
},
},
}),
);
const refusal = await failureOf(actions.execute(GMAIL_CALL, {}));
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/no app at all/);
expect(refusal.message).toMatch(/GMAIL_FETCH_EMAILS/);
expect(ran).toEqual([]);
});
test("a redirect that is not a url is refused rather than handed to a browser", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: async () => ({ items: [OURS] }) },
connectedAccounts: {
link: async () => ({
redirectUrl: { href: "https://backend.composio.dev/s/a-link" },
}),
},
}),
);
/*
* PRESENT, TRUTHY AND NOT A URL, which is the one shape the `if (!redirectUrl)` guard beside it
* cannot see. What is on the other side of that return is a `Location` header and a person's
* browser, so `[object Object]` would be a page nobody can visit, reported as the consent
* screen they were sent to.
*/
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
/*
* AND IT IS THE SHAPE REFUSAL RATHER THAN THE ONE A LINE BELOW IT. `authorize` writes two
* sentences one line apart — this one and the `!redirectUrl` "connected by entering a
* credential rather than by visiting a page" — and a test asserting only "it refused, and not
* in a crash's words" cannot tell them apart: replacing this sentence with that one verbatim
* left this test green. The remedies are different acts by different people, so the sentence
* is named.
*/
expectOnlyRefusal(refusal.message, "redirectPage", "linear");
});
});
/**
* The field guards, held to the behaviour each was written for.
*
* EVERY TEST HERE COVERS A GUARD THAT WAS ALREADY IN THE FILE AND HAD NOTHING HOLDING IT. That is
* worse than an untested new behaviour rather than better: a guard nothing reddens for is read by
* the next person as ceremony over a field the SDK's own types already promise, and deleting it
* leaves a green suite. Each one below was therefore checked by removing the guard it covers and
* watching this test fail.
*/
describe("what a malformed field of a row actually costs", () => {
const CATALOGUE_ROWS: {
fault: string;
row: unknown;
/*
* THE REFUSAL BY NAME, AND THE ROW IT WAS RAISED OVER, RATHER THAN A WORD OUT OF ITS PROSE.
* This column held a bare `RegExp` and the loop asserted presence only, so the six patterns
* were not mutually exclusive: `/slug/` matched the NAME fault's sentence ("gmail is a slug
* rather than a title") and `/name/` matched the SLUG fault's ("the slug is the only name this
* deployment has for an app"), and swapping which field the two guards read left all six green.
* {@link expectOnlyRefusal} asserts the named sentence AND the absence of every sibling in the
* registry, which is the cross-check this table was the one place in the file to go without.
*/
says: RefusalName;
at?: string;
}[] = [
{
fault: "a slug that arrived as null",
// The slug is the only name this deployment has for an app: it is what enabling one writes
// into a url and what every later call names, so a row without one is an app whose Add button
// records something nothing can act on. Deleting this guard left the suite green.
row: { slug: null, name: "Gmail", meta: {} },
/*
* THE WHOLE CLAUSE RATHER THAN THE WORD, BECAUSE THE TWO SENTENCES EACH CARRY THE OTHER'S
* WORD. This asked `/slug/` and its sibling two rows down asked `/name/`, and the slug's own
* refusal says "The slug is the only NAME this deployment has for an app" while the name's
* says "and gmail is a SLUG rather than a title" — so each matched the other's fault, and
* swapping which field the two guards read left all six of these tests green. What
* discriminates is the position the value was sent in, which is the phrase both refusals are
* built on and the only part of either that a swap moves.
*/
says: "catalogueSlug",
at: "row 1 of Composio's app catalogue",
},
{
fault: "a logo that is not an address",
// This value is put in an image address on an administrator's picker. Deleting this guard
// also left the suite green: the object went into `src` and the page showed a broken image.
row: {
slug: "gmail",
name: "Gmail",
meta: { logo: { url: "https://example.test/gmail.png" } },
},
says: "catalogueLogo",
at: "gmail",
},
{
fault: "a name that arrived as null",
// `?? ""` here is an app in an administrator's picker with nothing written on it, and `gmail`
// is a slug rather than a title.
row: { slug: "gmail", name: null, meta: {} },
// The position rather than the word, for the reason the slug row above gives at length.
says: "catalogueName",
at: "row 1 of Composio's app catalogue",
},
{
fault: "a description that is not text",
row: { slug: "gmail", name: "Gmail", meta: { description: 12 } },
says: "catalogueDescription",
at: "gmail",
},
{
fault: "a category with no name",
// The categories are the words a person chooses an app by, so a blank one is a filter nobody
// can use rather than a cosmetic gap.
row: {
slug: "gmail",
name: "Gmail",
meta: { categories: [{ id: "productivity" }] },
},
says: "catalogueCategoryName",
at: "gmail's category 1",
},
{
fault: "an action count that arrived as a string",
// `Number("63")` is the defect this whole sweep is about: a vendor change turned into a
// plausible figure, shown BEFORE anybody enables an app, that nobody would think to question.
row: { slug: "gmail", name: "Gmail", meta: { tools_count: "63" } },
says: "catalogueActionCount",
at: "gmail",
},
];
for (const { fault, row, says, at } of CATALOGUE_ROWS) {
test(`a catalogue row with ${fault} stops the directory`, async () => {
const { broker } = buildComposioClient(
fakeVendor({ toolkits: { list: async () => ({ items: [row] }) } }),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expectOnlyRefusal(refusal.message, says, at);
});
}
/**
* THE ACTION ROW HAS ONE FAULT LEFT, AND FOUR TESTS HERE WERE ABOUT SHAPES IT CANNOT HAVE.
*
* A description that is not text, an `inputParameters` that is a string of JSON, tags that are
* not all labels and a version that is a number each had a row in a table beside this one, and
* each was answered by a refusal in the adapter. Running `@composio/core` 0.18.1 shows all four
* dying one layer earlier: `transformToolCases` ends in `ToolSchema.parse(...)` — a throwing
* parse, not the warn-only `transform()` the other three listings go through
* (`src/models/Tools.ts:193`) — and both calls this adapter makes run through it (`:561`, `:719`).
* Every one of those four fixtures produces a `ZodError` from inside the SDK, which `./composio`'s
* `isSchemaMismatch` already recognises and answers with the same package remedy. So the tests
* were green over guards nothing could reach, which is the worst of the three states: a reader
* takes both the guard and the test as proof the path is watched.
*
* WHAT `ToolSchema` LEAVES OPEN IS THE ONE BELOW. `slug: z.string()` is satisfied by the empty
* string, and this slug is not a label: it becomes `mcp_tools.name`, which is NOT NULL and half
* that table's primary key, it is what a grant points at, and it is what a later call sends back
* to Composio. That is the fault this listing still has to refuse, and it is the only one.
*/
test("an action whose slug is blank stops the listing rather than being written", async () => {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async () => ({
items: [
{ slug: "GMAIL_FETCH_EMAILS", name: "Fetch emails" },
{ slug: " ", name: "Send mail" },
],
}),
},
}),
);
const refusal = await failureOf(
actions.listActions("gmail", { limit: WHOLE_LISTING }),
);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/slug/);
// Which row, because an administrator reading this off a Plugins page has a listing of sixty
// actions and no other way to tell which of them Composio named with nothing.
expect(refusal.message).toMatch(/row 2/);
// And what it cost them, which is nothing: a refusal here leaves the actions already recorded
// for the app in place rather than replacing them with a listing one row short.
expect(refusal.message).toMatch(/tools already held are untouched/);
});
/**
* A CATEGORY THAT IS NOT A CATEGORY IS DESCRIBED AS WHAT ARRIVED, NOT AS A MISSING NAME.
*
* The non-object guard here was deleted on the stated ground that the SDK dereferences a category
* and dies before this file sees one. Running `@composio/core` 0.18.1 says otherwise: `("crm").id`
* is `undefined` and not a throw, so a string, a number or a boolean in that list survives
* `transformToolkitListResponse` — only null and undefined die there. What the refusal then said
* was "Composio sent nothing where the name of gmail's category 1 belongs", about a value that
* was the string "crm", which sends an operator looking in a dashboard for a category with a
* missing name. There is no such category.
*
* THE ASSERTION IS ON THE TWO SENTENCES BEING DIFFERENT, because a test that only required a
* refusal was green over the whole defect: the catalogue was refused either way, and what was
* wrong was what the operator was told.
*/
for (const { fault, entry, names } of [
{ fault: "a string", entry: "crm", names: /a string/ },
{ fault: "a number", entry: 7, names: /a number/ },
]) {
test(`a category that arrived as ${fault} is named as one rather than as a missing name`, async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => ({
items: [
{ slug: "gmail", name: "Gmail", meta: { categories: [entry] } },
],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/gmail's category 1/);
expect(refusal.message).toMatch(names);
// And NOT the sentence for a category object whose name Composio omitted, which is the other
// fault and the other thing to go looking at.
expect(refusal.message).not.toMatch(/Composio sent nothing/);
});
}
/**
* A BLANK IDENTIFIER IS DESCRIBED AS BLANK RATHER THAN AS "A STRING".
*
* {@link textOf} decides emptiness on the TRIMMED value and `sent` tested `value === ""`, so the
* two disagreed about exactly one shape — the padded blank, which is the one a wire value
* actually arrives in. A config id of three spaces was refused for being empty and then described
* as "a string", which is a sentence with no finding in it: a string is what an id IS, so the
* reader is told the field was right and the call refused anyway.
*/
test("a config id that is nothing but spaces is not reported as a string", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [{ id: " ", name: "Linear (OpenBot)", status: "ENABLED" }],
}),
},
}),
);
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect((refusal.cause as Error).message).toMatch(/blank space/);
expect((refusal.cause as Error).message).not.toMatch(
/Composio sent a string where/,
);
});
/**
* THE THREE ACTION FIELDS THIS FILE HANDS ON, AND WHAT EACH BECOMES WHERE IT LANDS.
*
* The four deleted guards next door were deleted correctly — `ToolSchema.parse` really does raise
* a `ZodError` for them — and the argument was then taken one step too far, past the fields
* {@link ComposioAction} promises to `./composio` and `./store`. The parse is a fact about
* `getRawComposioTools` in one version of one package; the declaration is what the seam a test
* satisfies with a literal, and what the next version is read against, actually rest on.
*
* WHAT THAT COSTS IS NOT A REFUSAL, WHICH IS WHY IT BELONGS HERE. `storableTools` writes
* `(tool.description ?? "").replaceAll(NUL, "")` and `tool.version?.replaceAll(NUL, "")`, so a
* description or a version that is not a string is a bare "42.replaceAll is not a function"
* thrown from outside every vendor `try` in the adapter — a crash where this file's whole
* contract is a sentence. An `inputParameters` that is not an object is quieter: it is stored as
* the action's input schema and shown to a model as Composio's own.
*
* EACH ASSERTS THE FIELD IT IS ABOUT, because a table of refusals that only required a refusal
* would pass with one guard standing in for three.
*/
for (const { fault, row, names } of [
{
fault: "a description that is not text",
row: { slug: "GMAIL_FETCH_EMAILS", description: 42 },
names: /description/,
},
{
fault: "an input schema that is not an object",
row: { slug: "GMAIL_FETCH_EMAILS", input_parameters: "not-a-schema" },
names: /input schema/,
},
{
fault: "a version that is not text",
row: { slug: "GMAIL_FETCH_EMAILS", version: 20_260_903 },
names: /version/,
},
]) {
test(`an action with ${fault} stops the listing rather than crossing the seam`, async () => {
const { actions } = buildComposioClient(
fakeVendor({ tools: { list: async () => ({ items: [row] }) } }),
);
const failure = await failureOf(
actions.listActions("gmail", { limit: WHOLE_LISTING }),
);
expect(failure.message).not.toMatch(A_CRASH);
expect(failure.message).toMatch(names);
// The tools already recorded for the app are untouched, which is what makes refusing the
// right answer rather than a worse outage than the one being avoided.
expect(failure.message).toMatch(/tools already held are untouched/);
});
}
/**
* AND AN ACTION THAT PUBLISHES NONE OF THEM IS ORDINARY. Composio genuinely ships actions with no
* description and no version, and one with no parameters at all arrives with none — the SDK
* normalizes `{}` to absent before parsing. Absence is a fact about the action; present-and-wrong
* is a fact about the answer. A guard that could not tell them apart would refuse most of the
* catalogue.
*/
test("an action that publishes no description, schema or version is still listed", async () => {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: actionsOf("gmail", [{ slug: "GMAIL_FETCH_EMAILS" }]),
},
}),
);
expect(
await actions.listActions("gmail", { limit: WHOLE_LISTING }),
).toEqual([
{
slug: "GMAIL_FETCH_EMAILS",
description: undefined,
inputParameters: undefined,
tags: undefined,
version: undefined,
},
]);
});
/**
* AND `null` IS HOW THE WIRE SPELLS THAT ABSENCE, WHICH IS THE HALF THE THREE GUARDS ABOVE MISSED.
*
* `./composio` documents the exemption on the field beside these — "`null` IS NOT ONE OF THESE,
* and that is deliberate": an action with no version is listed with none, JSON says so with a
* null, and refusing it turns a healthy refresh into a total failure for every app that publishes
* one. Nothing about a null description or a null input schema is different, and a refusal here
* is the same total failure one layer lower down: the whole listing stops, so every OTHER action
* on the app loses its effect, its version and the grants pointing at it, on every refresh,
* permanently.
*
* WHAT EACH LANDS ON ALREADY READS A NULL. `./composio` maps `description ?? ""` and
* `inputParameters ?? {}` and `version?.trim()`, so the value crossing this seam as absent is the
* value those three lines were written for. So a null is normalized to absent HERE rather than
* handed on, because {@link ComposioAction} spells all three optional-and-typed and a null
* travelling under that declaration is the same untrue assertion the guards exist to stop.
*/
test("an action whose description, schema or version is null is still listed", async () => {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: actionsOf("gmail", [
{
slug: "GMAIL_FETCH_EMAILS",
description: null,
input_parameters: null,
version: null,
},
]),
},
}),
);
expect(
await actions.listActions("gmail", { limit: WHOLE_LISTING }),
).toEqual([
{
slug: "GMAIL_FETCH_EMAILS",
description: undefined,
inputParameters: undefined,
tags: undefined,
version: undefined,
},
]);
});
test("a nameless config stops the removal rather than being left standing", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [OURS, { id: "ac_nameless", status: "ENABLED" }],
}),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
/*
* WITHOUT THE GUARD THIS IS A REPORTED SUCCESS. A name read as "" fails the suffix test, so the
* row is sorted into somebody else's dashboard work and left standing — and `deleteAuthConfig`
* returns quietly, after which `removeServer` deletes the app's row. The config and every grant
* made against it outlive the removal with nothing in this deployment naming them.
*/
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
/*
* THE FIELD IS ASKED OF THE SENTENCE THAT ESTABLISHED IT, NOT OF THE ONE THAT SUMS BOTH UP.
* This asked `/name/` of `message`, whose whole clause about the leftover rows is "with no id
* or no name" — a phrase carrying both words, so this test and the one below it each passed on
* the other's fault, and swapping the two guards in `readableConfigs` left the pair green. The
* finding lives on `cause`, where one row's own reading is written down, so that is where it is
* read from — and the other field's sentence is asserted absent, which is the half that makes
* the assertion discriminating rather than merely more specific.
*/
expectOnlyRefusal(
everythingSaidBy(refusal).join("\n"),
"configName",
"row 2 of Composio's authorization configs for linear",
);
/*
* AND THE CONFIG THAT WAS READABLE IS GONE, WHICH THIS ASSERTED THE OPPOSITE OF ON PURPOSE AND
* IS CHANGED ON PURPOSE. It required `[]` — not even the row that WAS readable — on the ground
* that a half-done removal reported as done is the state being avoided. The first half of that
* is right and the second half does not describe this: the call still refuses, so `removeServer`
* never deletes the app's row and nothing is reported as done. What the old shape actually
* bought was a permanent block. The unreadable row is unreadable on every retry, so the app
* could never be removed at all while a config of ours held live grants the whole time — which
* is the defect the accounts path was corrected for one wave earlier, sitting one function
* away. Every config this deployment CAN name goes, and the row it cannot is what the refusal
* counts.
*/
expect(deleted).toEqual([["ac_ours", { revoke_on_delete: true }]]);
// And the remedy for the row that is left is the dashboard rather than the button just pressed,
// because the next press meets exactly the same unreadable row.
expect(refusal.message).toMatch(/Composio's own dashboard/);
});
test("a config with no id stops the removal, and no delete is sent", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [{ name: "Linear (OpenBot)", status: "ENABLED" }],
}),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
/*
* A DELETE WITHOUT AN ID IS A REQUEST COMPOSIO IS FREE TO READ AS ANYTHING, answered however it
* likes, after which this deployment records that the app was withdrawn. The assertion is on
* what went out rather than on what came back for exactly that reason.
*/
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
// Asked of the sentence that established it and not of the shared "with no id or no name"
// clause, for the reason the test above gives: that phrase carries both words.
expectOnlyRefusal(
everythingSaidBy(refusal).join("\n"),
"configId",
"row 1 of Composio's authorization configs for linear",
// Every row of this listing is one nothing could sort, so the top sentence is that state's
// own and the id fault is what hangs off it. Named rather than tolerated, because a chain
// carrying a sibling nobody declared is the shape this helper exists to redden.
["unreadableNothingRemoved"],
);
expect(deleted).toEqual([]);
});
/**
* NOTHING READABLE AT ALL IS NOT A REMOVAL THAT WENT HALF WAY, AND THE COUNT SAID IT WAS.
*
* Every one of this listing's rows is one `readableConfigs` could not sort, so there is nothing of
* this deployment's to delete and nothing of anybody else's to leave standing — `held` is empty,
* which is the branch above this one, and `ours` is empty, which is the delete loop's. The loop
* therefore ran over nothing and the partial-withdrawal sentence reported "Composio removed 0 of
* this deployment's 0 authorization configs for linear": two figures measured off a set that was
* never read, in the one sentence an operator is meant to act on. Its remedy is wrong with them —
* "the app has not been FULLY withdrawn" says a part of it was — and the reachable half of the
* finding is the rows themselves, which is a dashboard reading rather than a second press.
*/
test("a listing whose only rows are unreadable is refused as that rather than as half a removal", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ name: "Linear (OpenBot)", status: "ENABLED" },
{ id: "ac_b", status: "ENABLED" },
],
}),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
const refusal = await failureOf(broker.deleteAuthConfig("linear"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// No count of a set nothing read, in either position.
expect(refusal.message).not.toMatch(/removed \d+ of this deployment's \d+/);
// What actually happened, and what was actually found.
expect(refusal.message).toMatch(/nothing was deleted/);
expect(refusal.message).toMatch(/2 of its authorization configs/);
expect(deleted).toEqual([]);
// And both readings travel, because the count is deliberately the whole of the sentence.
const said = everythingSaidBy(refusal).join("\n");
expect(said).toMatch(/where the id of row 1/);
expect(said).toMatch(/where the name of row 2/);
});
test("an unreadable status names every config's own, not the first one's for all of them", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ id: "ac_a", name: "Linear (OpenBot)", status: "PENDING" },
{ id: "ac_b", name: "Linear (OpenBot)", status: "SUSPENDED" },
],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
/*
* TWO CONFIGS, TWO STATUSES, AND THE SENTENCE COUNTED BOTH AND QUOTED ONE — asserting of the
* pair a fact it had established of the first. The status is quoted because it is the one
* thing an operator can search a dashboard and a changelog for, and an operator given PENDING
* would never find the config that says SUSPENDED.
*/
expect(refusal.message).toMatch(/"PENDING"/);
expect(refusal.message).toMatch(/"SUSPENDED"/);
expect(refusal.message).toMatch(/2 of this deployment's 2/);
});
/**
* THE ONE THAT DID NOT FIT IS ONE WORD, AND THE SENTENCE SAID "1 other words".
*
* `STATUSES_NAMED` bounds how many distinct statuses a refusal names, and the tail counting what
* was left out is written as a bare plural — in a sentence whose very next clause conjugates its
* own verb for the count. An operator reading a refusal that cannot get its own number right is
* being asked to trust it about an authorization config.
*/
test("the statuses that did not fit are counted in the number's own words", async () => {
const WORDS = [
"PENDING",
"SUSPENDED",
"EXPIRED",
"REVOKED",
"ARCHIVED",
"DRAFT",
];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: WORDS.map((status, index) => ({
id: `ac_${index}`,
name: "Linear (OpenBot)",
status,
})),
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
// Five named and one left over, which is one WORD.
expect(refusal.message).toMatch(/and 1 other word,/);
expect(refusal.message).not.toMatch(/1 other words/);
});
/**
* A ROW NOTHING COULD SORT IS THE THIRD FACT THIS SENTENCE HAS, AND A SHADOWED NAME TOOK IT AWAY.
*
* `configsFor` answers three things, and one of them is the refusals for rows it could sort into
* neither pile. Inside the no-enabled-config branch of both `authorize` and `connectWithFields` a
* local list of the configs whose status is neither word was ALSO called `unreadable`, so the
* outer one was unreachable from the only place its clause could have been written — and an
* administrator holding one disabled config beside one row Composio described with no name was
* told to go and enable the disabled one, full stop. That instruction may not be the remedy at
* all: the row that could not be sorted may be a config of this deployment's that Composio calls
* ENABLED, in which case there was nothing to enable and the thing to read is the dashboard.
*
* THE DISABLED CLAUSE STAYS, WHICH IS THE POINT OF ASSERTING BOTH. These are two facts about two
* different rows, and the file's own rule for that shape — stated at length one method up — is two
* independent clauses rather than a chain, so that neither takes the other's turn.
*/
test("a disabled config beside a row nothing could sort names both remedies", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ id: "ac_a", name: "Linear (OpenBot)", status: "DISABLED" },
{ id: "ac_b", status: "ENABLED" },
],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/calls 1 of this deployment's 1 authorization configs for linear disabled/,
);
expect(refusal.message).toMatch(
/1 of its authorization configs for linear in a way this deployment cannot read/,
);
});
/** The same block, one method over, because it is a copy of that one rather than a call to it. */
test("the typed-secret path names the row nothing could sort too", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ id: "ac_a", name: "Linear (OpenBot)", status: "DISABLED" },
{ id: "ac_b", status: "ENABLED" },
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: "pplx-secret" },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/calls 1 of this deployment's 1 authorization configs for linear disabled/,
);
expect(refusal.message).toMatch(
/1 of its authorization configs for linear in a way this deployment cannot read/,
);
// And what they typed is nowhere in it, which is this method's own standing rule.
expect(refusal.message).not.toMatch(/pplx-secret/);
});
test("a status that is not a vendor enum name is described rather than repeated", async () => {
/*
* THIS BRANCH IS REACHED PRECISELY BECAUSE THE VALUE IS NOT ONE OF THE WORDS THE CODE EXPECTS,
* so "it is a closed set of enum names" — the whole argument for quoting it — is the one thing
* that cannot be assumed here. What arrives is whatever came off the wire, and the refusal it
* lands in is read off an admin page, written into an app's `lastError` and put in front of a
* model.
*/
const WIRE = `<!doctype html>\n<title>502 Bad Gateway</title>\n${"x".repeat(20_000)}`;
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [{ id: "ac_a", name: "Linear (OpenBot)", status: WIRE }],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal.message).not.toContain("502 Bad Gateway");
expect(refusal.message).not.toContain("x".repeat(64));
expect(refusal.message.length).toBeLessThan(1000);
// Still a refusal, and still one naming the state: what the value IS remains the finding even
// where the value itself is not safe to repeat.
expect(refusal.message).toMatch(/neither ENABLED nor DISABLED/);
expect(refusal.message).toMatch(/a string/);
});
test("the config a connection is begun against is chosen in one order everywhere", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [
{ id: "ac_a", name: "Linear (OpenBot)", status: "ENABLED" },
{ id: "ac_B", name: "Linear (OpenBot)", status: "ENABLED" },
],
}),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
() => 1_000_000,
);
await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
/*
* `ac_B` BECAUSE "B" IS 0x42 AND "a" IS 0x61, which is the same answer on every machine. Under
* `localeCompare` with no locale it is the HOST that decides — an English collation puts
* `ac_a` first — and the two callers this order exists to keep in step are a person pressing
* Connect and an administrator pressing Remove, who need not be answered by the same process,
* container or build of ICU. This pair is the one that tells the two orders apart.
*/
expect(linked).toEqual([
[VENDOR_USER, "ac_B", { callbackUrl: RETURN_URL }],
]);
});
test("a created config the answer does not name is reported as possibly standing", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({ items: [] }),
// The create was accepted; what came back carries no id. The answer used to be awaited
// and dropped, so this was a successful enable of an app whose config nothing here could
// show existed.
create: async () => ({}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/may well be standing/);
expect(refusal.message).toMatch(/enabling linear again finds it/);
});
test("a create whose reply the SDK could not read does not claim nothing was created", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({ items: [] }),
/*
* What `transformCreateAuthConfigResponse` does to an answer with no `auth_config`: it
* reads `response.auth_config.id` (`@composio/core` 0.18.1,
* `src/utils/transformers/authConfigs.ts:96-106`) and raises inside the vendor's own
* package — AFTER the create has been sent and answered.
*/
create: async (): Promise<never> => {
throw new TypeError(
"undefined is not an object (evaluating 'response.auth_config.id')",
);
},
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.ensureAuthConfig({
toolkit: "linear",
name: "Linear",
connection: { kind: "consent" },
}),
);
/*
* THE ONE CONDITION MOST LIKELY TO MEAN THE CONFIG EXISTS WAS THE ONE SAYING IT DID NOT. The
* `TypeError` row translates a fault raised inside `@composio/core` while it READ a reply, so
* by the time this sentence is composed the request has gone out and Composio has answered it
* — and the outcome clause read "no authorization config was created for linear".
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(/no authorization config was created/);
expect(refusal.message).toMatch(
/whether an authorization config for linear now stands at Composio is not something this deployment can tell/,
);
});
const UNSETTLED: { fault: string; status: unknown }[] = [
{ fault: "a status this deployment has never heard of", status: "PENDING" },
{ fault: "no status at all", status: undefined },
];
for (const { fault, status } of UNSETTLED) {
test(`a config of ours with ${fault} refuses in its own words`, async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => ({
items: [{ id: "ac_ours", name: "Linear (OpenBot)", status }],
}),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
/*
* NEITHER OF THE OTHER TWO REMEDIES, which is the whole of what this asserts. Telling an
* operator the config is disabled sends them to a dashboard to enable something that may
* already be enabled, and leaves them with a page insisting on a fact they can see is false;
* telling them there is no config sends them to remove and re-add an app whose config is
* sitting right there. The state is UNKNOWN, and only a sentence saying so is honest.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(DISABLED_REMEDY);
expect(refusal.message).not.toMatch(NO_CONFIG_REMEDY);
// And still a refusal: consent spent against a config this deployment cannot show is enabled
// attaches nothing, and cannot be spent again without sending the person round a second time.
expect(linked).toEqual([]);
});
}
});
/**
* WHAT A FIELD COMPOSIO PADDED IS WORTH, WHICH IS THE FIELD AND NOT THE FIELD PLUS ITS PADDING.
*
* `textOf` decided emptiness on the TRIMMED string and answered the PADDED one — a guard that
* checked one value and passed along another — so every identifier this adapter reads travelled
* with whatever whitespace the wire wrapped it in. Not one of the four below is cosmetic: three of
* them are what a later REQUEST names, and the fourth is both sides of the one comparison this
* file refuses a call on.
*
* WHY A VENDOR WOULD SEND ONE AT ALL is the same reason `madeHere` tolerates a trailing space in a
* config's name: these values pass through dashboards where people type, paste and edit them.
*/
describe("a field Composio padded with whitespace", () => {
test("a padded slug and title reach the picker as the app's own name", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => ({
items: [
{ slug: " gmail ", name: " Gmail ", meta: { tools_count: 63 } },
],
}),
},
}),
() => 1_000_000,
);
const [app] = await broker.listApps();
/*
* THE SLUG IS THE ONE THAT COSTS SOMETHING. `addBrokeredApp` composes `composio://<slug>` from
* exactly this value, and `toolkitOf` reads the app back out of that url through a character
* class that admits no spaces — so a padded slug here is an enabled app whose url names no app
* at all, and every later call through it refuses.
*/
expect(app?.slug).toBe("gmail");
expect(app?.name).toBe("Gmail");
});
test("a padded config id is what the delete names, without the padding", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: " ac_ours ", name: "Linear (OpenBot)", status: "ENABLED" },
]),
delete: async (...call: unknown[]) => {
deleted.push(call);
},
},
}),
);
await broker.deleteAuthConfig("linear");
// The id is the whole of what a deletion names, and this one was sent verbatim: Composio is
// asked to remove an object with a name nobody holds, and this deployment records a withdrawal.
expect(deleted).toEqual([["ac_ours", { revoke_on_delete: true }]]);
});
test("a padded account id is what the withdrawal names", async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: ourGmailConfig },
connectedAccounts: {
list: heldAccounts([{ id: " ca_1 " }]),
delete: async (...call: unknown[]) => {
deleted.push(call);
return WITHDRAWN;
},
},
}),
);
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
expect(deleted).toEqual([["ca_1", { revoke_on_delete: true }]]);
});
test("a padded action slug is recorded as the action rather than as one nothing can call", async () => {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async () => ({
items: [{ slug: " GMAIL_FETCH_EMAILS ", version: "20260903_00" }],
}),
},
}),
);
const [action] = await actions.listActions("gmail", {
limit: WHOLE_LISTING,
});
// This becomes `mcp_tools.name`, which is half that table's primary key, what a grant points at
// and what the next call sends back to Composio.
expect(action?.slug).toBe("GMAIL_FETCH_EMAILS");
});
test("a padded app slug on the vendor's answer is not a mismatch", async () => {
const ran: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
getRawComposioToolBySlug: async () => ({
slug: "GMAIL_FETCH_EMAILS",
toolkit: { slug: " gmail " },
}),
execute: async (...call: unknown[]) => {
ran.push(call);
return { successful: true, data: {}, error: null };
},
},
}),
);
/*
* THE MISMATCH REFUSAL IS THE ONE PLACE THIS FILE REFUSES TO RUN SOMETHING, and it exists for a
* url edited between a refresh and a call. A padded slug is not that: it is the same app,
* refused with a sentence naming a remedy — refresh this app's tools — that cannot change what
* Composio pads.
*/
await actions.execute(
{
toolkit: "gmail",
slug: "GMAIL_FETCH_EMAILS",
userId: "user_1",
version: "20260903_00",
},
{},
);
expect(ran).toHaveLength(1);
});
/**
* THE CONSENT PAGE IS THE ONE VENDOR VALUE THAT LEAVES THIS PROCESS IN A `Location` HEADER.
*
* Every other identifier on this path goes through the file's own trimming read; the url this
* method answers did not, so a padded one was returned with its padding and put in front of a
* browser. " https://… " is not an address — the space is percent-encoded or the redirect is
* refused outright — so a person who pressed Connect lands on nothing, having been told they were
* being sent to the app's own consent screen.
*/
test("a padded consent page is the address this person is sent to, without the padding", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: {
link: async () => ({
redirectUrl: " https://backend.composio.dev/s/a-link ",
}),
},
}),
() => 1_000_000,
);
const begun = await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
expect(begun).toEqual({
redirectUrl: "https://backend.composio.dev/s/a-link",
// Declared null: Composio's return leg is correlated by sealed state, not by a broker id.
authorizationId: null,
});
});
/**
* AND A URL OF BLANK SPACE IS NO PAGE AT ALL, WHICH IS THE ONE SHAPE BOTH GUARDS LET THROUGH.
*
* The shape guard above it asks only whether the value is a string, and `!redirectUrl` is false
* for " " — so three spaces cleared both and were handed back as the address of a consent
* screen. That is the same emptiness this file's own trimming read already calls absent
* everywhere else: an identifier that reads as present at every glance and is unusable.
*/
test("a consent page of blank space is no page to visit rather than a page", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: " " };
},
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
// The link WAS minted — this is the vendor's answer to it — so the assertion is about what
// came back rather than about the call not having gone out.
expect(linked).toHaveLength(1);
expectOnlyRefusal(refusal.message, "noPageRemedy");
});
/**
* A PADDED STATUS WAS REFUSED AND THEN QUOTED WITHOUT ITS PADDING, WHICH IS A SENTENCE THAT
* CONTRADICTS ITSELF IN FRONT OF THE OPERATOR READING IT.
*
* `=== "ENABLED"` is the RAW status and `named` quotes the TRIMMED one, so " ENABLED " fell
* through to the no-enabled-config branch and was reported there as `"ENABLED", which is neither
* ENABLED nor DISABLED`. The remedy attached to it is a package upgrade, for a config that
* Composio calls enabled and that this deployment made. The two readings of one field now agree,
* and the config is what a connection is begun against.
*/
test("a padded ENABLED is the config a connection is begun against", async () => {
const linked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: " ENABLED " },
]),
},
connectedAccounts: {
link: async (...call: unknown[]) => {
linked.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
},
},
}),
() => 1_000_000,
);
const begun = await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
});
expect(begun).toEqual({
redirectUrl: "https://backend.composio.dev/s/a-link",
// Declared null: Composio's return leg is correlated by sealed state, not by a broker id.
authorizationId: null,
});
expect(linked).toEqual([
[VENDOR_USER, "ac_ours", { callbackUrl: RETURN_URL }],
]);
});
/** The same read, one method over, because that block is a copy of this one rather than a call. */
test("a padded ENABLED is the config a typed secret is attached to", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: " ENABLED " },
]),
},
connectedAccounts: {
create: async (body: unknown) => {
created.push(body);
return { id: "ca_made" };
},
},
}),
);
expect(
await broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: "pplx-secret" },
}),
).toEqual({ accountId: "ca_made" });
expect(created).toHaveLength(1);
});
/**
* AND A PADDED DISABLED IS DISABLED, which is the other half of the same disagreement.
*
* `!== "DISABLED"` over the raw value sorted " DISABLED " into the unsettled pile, so an operator
* holding one disabled config was told their package was out of date and never told the one act
* that would have got somebody connected: enabling it in Composio's own dashboard.
*/
test("a padded DISABLED is told as disabled rather than as a word nothing knows", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: " DISABLED " },
]),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(
broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
returnUrl: RETURN_URL,
}),
);
expect(refusal.message).toMatch(
/calls 1 of this deployment's 1 authorization configs for linear disabled/,
);
expect(refusal.message).not.toMatch(/neither ENABLED nor DISABLED/);
expectOnlyRefusal(refusal.message, "disabledRemedy");
});
/**
* A PADDED CONNECTION MODE IS THE MODE THE APP WAS ENABLED AS, and it was read as one the app had
* stopped publishing.
*
* `labelsOf` already trims every scheme this deployment records, on the stated ground that a
* scheme is the NAME of a flow and a padded `" OAUTH2 "` is the app's own. The mode published
* beside the form's fields is the same word compared against the same recorded one, and it was
* the one read that skipped the trim — so an app whose vendor padded the mode told an
* administrator to remove it and add it again, which records the same padded word and comes back
* refusing identically.
*/
test("a padded connection mode still draws the form the app publishes", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: " API_KEY ",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API Key",
type: " string ",
required: true,
is_secret: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
/*
* AND THE TYPE OF THE BOX IS THE SAME READ ONE FIELD IN. `row.type !== "string"` was the raw
* value while the name beside it went through the trim, so a padded `" string "` was refused
* with "a box this deployment can draw is a string" — about a field whose type IS string.
*/
expect(
await broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "generic_api_key",
label: "API Key",
help: "",
required: true,
secret: true,
},
]);
});
});
/**
* WHICH `delete` THE VENDOR OBJECT ACTUALLY CARRIES, asserted without a network and without a key.
*
* THIS IS THE ONE DECISION IN {@link createComposioClient} AND NOTHING REACHED IT. That function is
* described in its own comment as too thin to have a bug in, and it is — except for two lines.
* `Composio`'s own `authConfigs.delete` and `connectedAccounts.delete` hard-code the request body
* they send (`@composio/core` 0.18.1, `src/models/AuthConfigs.ts:303-311`,
* `src/models/ConnectedAccounts.ts:532-540`), so through them `revoke_on_delete` cannot be passed at
* all and every delete soft-deletes while the grant at Google or Slack stands. Both are therefore
* satisfied from `composio.getClient()` instead, and that routing is the whole reason this
* deployment's withdrawals withdraw anything.
*
* EVERY OTHER TEST IN THIS FILE DRIVES {@link buildComposioClient}, which takes the vendor object
* already assembled — so the four that assert `revoke_on_delete` went out assert it about a double,
* and none of them can see which function `createComposioClient` put behind it. Swapping those two
* lines back to `composio.authConfigs.delete` and `composio.connectedAccounts.delete` type-checks
* and leaves this suite green while restoring the exact defect the flag was added for. The only
* thing that ever exercised the real wiring was `composio-live.test.ts`, which is skipped in every
* run that has no key — which is every ordinary run.
*
* WHAT MAKES IT OBSERVABLE OFFLINE IS THAT BOTH CLIENTS ARE CONSTRUCTIBLE WITHOUT DIALLING
* ANYTHING. `new Composio({ apiKey })` opens no socket once tracking and the npm version check are
* off, `getClient()` hands back the underlying `@composio/client` it already holds, and the methods
* of both live on their classes' prototypes. So a prototype replaced BEFORE `createComposioClient`
* runs is what the client it builds will call: the SDK's telemetry wrapper copies each method off
* the prototype at construction (`src/telemetry/Telemetry.ts:95-116`), and the raw client's
* resources carry no own properties at all. Four recorders — one on each side of each delete — turn
* "which function was reached" into a list, which is a fact about the wiring rather than about a
* request that was never made.
*
* THE IMPORT OF `@composio/core` HERE DOES NOT BREAK THE ONE-IMPORT-SITE RULE. That rule is about
* `server/src`, so that a version bump has exactly one FILE of product code to be read against;
* this is a test, and the version it is written against is the whole of what it asserts.
*/
describe("the key becoming a vendor, and which delete that vendor carries", () => {
/** One class's methods, as the object a replacement is written onto. */
type Methods = Record<string, (...args: unknown[]) => Promise<unknown>>;
const methodsOf = (instance: object): Methods =>
Object.getPrototypeOf(instance) as Methods;
test("both deletes are the raw client's, and neither is the SDK's own wrapper", async () => {
/*
* A SECOND CLIENT, BUILT ONLY TO REACH THE CLASSES. Nothing is called on it: it exists because
* the prototypes are not exported, and the way to a prototype is an instance. The key is a
* string nobody will ever send anywhere, which is the point of asserting this without one.
*/
const seed = new Composio({
apiKey: "never-dialled",
allowTracking: false,
disableVersionCheck: true,
});
const sdkAccounts = methodsOf(seed.connectedAccounts);
const sdkConfigs = methodsOf(seed.authConfigs);
const rawAccounts = methodsOf(seed.getClient().connectedAccounts);
const rawConfigs = methodsOf(seed.getClient().authConfigs);
const restore: { on: Methods; name: string; was: Methods[string] }[] = [];
const replace = (on: Methods, name: string, answer: Methods[string]) => {
restore.push({ on, name, was: on[name] });
on[name] = answer;
};
const reached: string[] = [];
const recorder =
(whose: string): Methods[string] =>
async (...call: unknown[]) => {
reached.push(`${whose} ${JSON.stringify(call)}`);
return { success: true };
};
try {
/*
* BOTH SIDES OF BOTH DELETES ARE RECORDED, which is what makes the list an assertion rather
* than a spy. A recorder on the raw client alone would still fire if the SDK's wrapper were
* used, because the wrapper calls straight through to it — so what tells the two wirings
* apart is whose recorder answered, and the only way to see that is to have one on each.
*/
replace(
rawAccounts,
"delete",
recorder("the raw client's connectedAccounts.delete"),
);
replace(
sdkAccounts,
"delete",
recorder("the SDK's own connectedAccounts.delete"),
);
replace(
rawConfigs,
"delete",
recorder("the raw client's authConfigs.delete"),
);
replace(
sdkConfigs,
"delete",
recorder("the SDK's own authConfigs.delete"),
);
// The two listings that carry each delete to its argument. Answered from memory, so this test
// reaches the network exactly as often as it reaches the live Composio account: never.
replace(sdkAccounts, "list", async () => ({
items: [{ id: "ca_1" }],
nextCursor: null,
}));
replace(sdkConfigs, "list", async () => ({
items: [OUR_GMAIL],
nextCursor: null,
}));
const { broker } = createComposioClient("never-dialled");
expect(
await broker.revoke({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
}),
).toBe(true);
await broker.deleteAuthConfig("gmail");
} finally {
// Restored whatever happened above, because these are the SDK's own classes and every later
// test in this process would otherwise be running against a patched vendor.
for (const { on, name, was } of restore.reverse()) on[name] = was;
}
/*
* THE WHOLE OF WHAT WAS REACHED, IN ORDER. An implementation that routed either delete through
* the SDK's wrapper puts that wrapper's name in this list, and the equality says so; one that
* dropped the flag puts a different argument list in it. Both are the same defect seen from
* two sides, and neither is visible to any other test in this file.
*/
expect(reached).toEqual([
`the raw client's connectedAccounts.delete ["ca_1",{"revoke_on_delete":true}]`,
`the raw client's authConfigs.delete ["${OUR_GMAIL.id}",{"revoke_on_delete":true}]`,
]);
});
/**
* WHICH OF THE TWO IDENTIFIERS GOES FIRST WHEN A CONSENT LINK IS MINTED, asserted at the seam.
*
* `connectedAccounts.link(userId, authConfigId, options)` takes two strings in a row, so swapping
* them is the one mistake a type checker is structurally unable to see — both arguments are
* `string`, and the call compiles either way. What it produces is not an error either: Composio
* is asked to link the account of a "person" named `ac_gmail_ours` against an auth config named
* `user_1`, which is a request about two things that do not exist rather than a malformed one.
*
* AND EVERY OTHER TEST IN THIS FILE IS BLIND TO IT for the reason the deletes above are. They
* drive {@link buildComposioClient} with a double whose `link` records positionally, so they
* assert the order the ADAPTER passes — which is correct and stays correct — while the line that
* re-spells those parameters on the way to the real SDK, inside {@link createComposioClient},
* is reached by nothing. Swapping it there type-checks and leaves this suite green.
*
* So the order is asserted where it is actually spent: against the SDK's own prototype, with the
* argument list recorded as it arrived.
*/
test("the consent link names this person first and the auth config second", async () => {
const seed = new Composio({
apiKey: "never-dialled",
allowTracking: false,
disableVersionCheck: true,
});
const sdkAccounts = methodsOf(seed.connectedAccounts);
const sdkConfigs = methodsOf(seed.authConfigs);
const restore: { on: Methods; name: string; was: Methods[string] }[] = [];
const replace = (on: Methods, name: string, answer: Methods[string]) => {
restore.push({ on, name, was: on[name] });
on[name] = answer;
};
const minted: unknown[][] = [];
let begun: {
redirectUrl: string;
authorizationId: string | null;
} | null = null;
try {
// The config listing is what carries the auth config's id to the link, so it answers with the
// one this deployment made — the id that must arrive SECOND.
replace(sdkConfigs, "list", async () => ({
items: [OUR_GMAIL],
nextCursor: null,
}));
replace(sdkAccounts, "link", async (...call: unknown[]) => {
minted.push(call);
return { redirectUrl: "https://backend.composio.dev/s/a-link" };
});
const { broker } = createComposioClient("never-dialled");
begun = await broker.authorize({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "gmail",
returnUrl: RETURN_URL,
});
} finally {
for (const { on, name, was } of restore.reverse()) on[name] = was;
}
// The person, then the config, then the callback — and the whole list rather than a field of
// it, because the defect this is written for is an order and not a value.
expect(minted).toEqual([
[VENDOR_USER, OUR_GMAIL.id, { callbackUrl: RETURN_URL }],
]);
expect(begun).toEqual({
redirectUrl: "https://backend.composio.dev/s/a-link",
// Declared null: Composio's return leg is correlated by sealed state, not by a broker id.
authorizationId: null,
});
});
});
/**
* WHAT CONSTRUCTING THE VENDOR IS ALLOWED TO DO TO THIS PROCESS, AND TO THE NETWORK, ON BOOT.
*
* `new Composio({ ... })` in {@link createComposioClient} carries three entries and every one of
* them is load-bearing, but none of them was visible to a test: the suite above drives
* {@link buildComposioClient}, which takes the vendor already assembled, so the construction
* literal could have any of its lines deleted and stay green. This describe is the only thing in
* the repository that reads that literal, and it reads it the way a deployment does — by watching
* what leaves the process.
*
* THE TWO FLAGS BOTH DEFAULT THE WRONG WAY FOR A SELF-HOSTED PRODUCT, which is why both are said
* rather than relied on. In `@composio/core` 0.18.1:
*
* - `allowTracking` defaults to TRUE (`src/utils/config-defaults/ConfigDefaults.node.ts:5`), and
* a true value runs `telemetry.setup(...)` (`src/composio.ts:380-390`). That does two separate
* things in one call. It POSTs an `SDK_INITIALIZED` metric to
* `https://telemetry.composio.dev/v1/metrics/invocations`
* (`src/services/telemetry/TelemetryService.ts:4,38-46`) — a third party's analytics, which
* the operator of a self-hosted install never opted into. And, first,
* `registerExitHandlers()` (`src/telemetry/Telemetry.ts:66,315-356`) installs THREE
* process-level listeners — `beforeExit`, `SIGINT` and `SIGTERM` — whose signal handlers flush
* telemetry, then `process.removeListener` and `process.kill(process.pid, signal)` to re-raise.
* That is a vendor library taking a hand in how this server shuts down, which is the part of
* the consequence that no amount of firewalling would undo.
* - `disableVersionCheck` defaults to FALSE (`src/composio.ts:113-120`), and a falsy value runs
* `checkForLatestVersionFromNPM` (`src/composio.ts:399-402`), which `fetch`es
* `https://registry.npmjs.org/@composio/core/latest` (`src/utils/version.ts:41-43`). A boot
* that reaches npm is a boot that depends on the vendor's release feed and on egress to it.
*
* AND THE KEY IS THE THIRD ENTRY, pinned here for the same reason. `apiKey` is not merely
* forwarded: dropping it does not fail, it FALLS BACK — `getSDKConfig` reads `COMPOSIO_API_KEY`
* from the environment and then `api_key` out of `~/.composio/user_data.json`
* (`src/utils/sdk.ts:42-52`), so a deployment could go on working against whichever account a
* machine happened to be logged into, with `config.composioApiKey` silently unused. The same
* request pins the absence of `baseURL`, because the host it goes to is the SDK's default
* (`src/utils/constants.ts:7`) and a `baseURL` added to the literal would move it.
*
* HOW IT IS OBSERVED WITHOUT A NETWORK: `globalThis.fetch` is replaced for the duration by one
* that records the request and rejects, and `process.on` by one that records the event name and
* installs nothing. Both are restored in a `finally`. So the transport is the recorder, no socket
* is opened either way, and the assertions are lists of what the vendor TRIED — which is the fact
* worth pinning, since a flag flipped back would be a try that succeeded in production.
*
* THE HANDLER HALF WOULD HAVE BEEN A VACUOUS ASSERTION AND IS NOT, which is worth knowing before
* anybody simplifies it. `registerExitHandlers` guards on an `exitHandlersRegistered` flag held by
* a MODULE-LEVEL singleton (`src/telemetry/Telemetry.ts:46,315-321`), so it fires at most once per
* process — and this file constructs more than one client, so under a dropped `allowTracking` an
* EARLIER test is what would install the handlers and this one would see an empty list and pass.
* That was observed, not theorised: with the flag deleted, the telemetry POST showed up here and
* the handler list did not. The helper below therefore clears that memo for the duration, which is
* what turns "no handler is installed" into "no handler was attempted".
*/
describe("what constructing the vendor is allowed to do on boot", () => {
/** One request as the stubbed transport saw it, which is all a test needs of a request. */
type Attempt = { url: string; apiKey: string | null };
/**
* Runs `body` with the network and the process's own listener registry replaced by recorders.
*
* `NODE_ENV` is forced away from `test` for the duration because the SDK's own
* `shouldSendTelemetry()` short-circuits on `test` and `ci`
* (`src/telemetry/Telemetry.ts:173-180`) — under `bun test` the telemetry POST would be
* suppressed by the runner's environment rather than by the flag, and a test that cannot tell
* those two apart is not pinning the flag.
*/
async function withRecordedTransport(
body: () => Promise<void> | void,
): Promise<{ attempts: Attempt[]; events: string[] }> {
const attempts: Attempt[] = [];
const events: string[] = [];
const realFetch = globalThis.fetch;
const realOn = process.on;
const realNodeEnv = process.env.NODE_ENV;
const memo = telemetry as unknown as { exitHandlersRegistered: boolean };
const realMemo = memo.exitHandlersRegistered;
globalThis.fetch = ((input: unknown, init?: RequestInit) => {
const request = input as { url?: string; headers?: HeadersInit };
const headers = new Headers(init?.headers ?? request?.headers ?? {});
attempts.push({
url: String(request?.url ?? input),
apiKey: headers.get("x-api-key"),
});
// Rejected rather than answered: every caller here treats the vendor call as one it is
// allowed to fail, and an answer would only invite a test about a body nobody sent.
return Promise.reject(new Error("no network in this test"));
}) as typeof globalThis.fetch;
process.on = ((event: string) => {
events.push(event);
return process;
}) as typeof process.on;
process.env.NODE_ENV = "production";
/*
* THE VENDOR'S ONCE-PER-PROCESS MEMO, CLEARED SO THE OBSERVATION IS AN OBSERVATION.
* `registerExitHandlers` returns early forever after its first call
* (`src/telemetry/Telemetry.ts:46,315-321`), and the flag lives on a module-level singleton
* shared by every `Composio` in the process. So if any earlier test in this file had
* constructed a tracking-enabled vendor, the handler list below would come back empty for a
* reason that has nothing to do with the flag under test — the assertion would pass while the
* defect it exists for was present. Reaching the private field is deliberate: it is the
* difference between recording that nothing was installed and recording that nothing tried.
*/
memo.exitHandlersRegistered = false;
try {
await body();
// One turn of the macrotask queue, because the SDK defers its initialisation metric through
// `queueMicrotask` (`src/telemetry/Telemetry.ts:241-257`) — a `setTimeout` lands after every
// microtask that defer could have queued, so the recorder sees the POST before it is undone.
await new Promise((resolve) => setTimeout(resolve, 0));
} finally {
globalThis.fetch = realFetch;
process.on = realOn;
process.env.NODE_ENV = realNodeEnv;
memo.exitHandlersRegistered = realMemo;
}
return { attempts, events };
}
test("it reaches nothing and installs no process handler", async () => {
const { attempts, events } = await withRecordedTransport(() => {
createComposioClient("never-dialled");
});
/*
* BOTH CONSEQUENCES IN ONE ASSERTION, so that a diff shows the whole of what a dropped flag
* costs rather than whichever half happened to be checked first.
*
* `reached` is what the vendor tried to dial. Dropping `disableVersionCheck: true` puts
* `https://registry.npmjs.org/@composio/core/latest` in it; dropping `allowTracking: false`
* puts `https://telemetry.composio.dev/v1/metrics/invocations` in it. The whole list is
* asserted rather than each absence, so a third endpoint a version bump added fails here too.
*
* `installed` is what the vendor attached to THIS process, and it is the half that no firewall
* would undo. Dropping `allowTracking: false` puts `beforeExit`, `SIGINT` and `SIGTERM` in it;
* the two signal handlers flush telemetry and then re-raise the signal themselves, so that
* deployment would have a vendor library sitting between an operator's Ctrl-C, or a container
* runtime's shutdown, and this server's exit.
*/
expect({
reached: attempts.map(({ url }) => url),
installed: events,
}).toEqual({
reached: [],
installed: [],
});
});
test("the key it was given is the key the vendor sends, to Composio's own host", async () => {
const { attempts } = await withRecordedTransport(async () => {
const { broker } = createComposioClient("never-dialled");
// It rejects because the transport above rejects; what is under test is the request that was
// built before it did, not the refusal that comes back.
await expect(broker.listApps()).rejects.toThrow();
});
/*
* EVERY attempt, not the first one, because the claim worth making is about all of them. The
* raw client retries a connection error, so there is more than one here and each carries the
* same key to the same host; and a client that had acquired a second destination — the
* telemetry endpoint being the one this SDK reaches for — would be a client for which this
* sentence had stopped being true, which is the failure this shape catches and an assertion
* about `attempts[0]` would not.
*/
expect(attempts.length).toBeGreaterThan(0);
for (const attempt of attempts) {
expect(attempt.apiKey).toBe("never-dialled");
expect(new URL(attempt.url).origin).toBe("https://backend.composio.dev");
}
});
});
/**
* THE TWO LISTINGS THAT USED TO REFUSE A FULL PAGE, NOW READ TO THE END OF THEIR CURSORS.
*
* These were the last two places in this file where a request the vendor can answer was described
* as one this deployment cannot express. It can: `@composio/client` 0.1.0-alpha.76 declares
* `cursor` on both `ToolkitListParams` (`resources/toolkits.d.ts:467-478`) and `ToolListParams`
* (`resources/tools.d.ts:421-432`), and `next_cursor` on both responses (`:322-326` and
* `:200-204`). What had no cursor was the WRAPPER around them — `transformToolkitListResponse`
* returns `response.items.map(...)`, a bare array with the cursor dropped, and
* `ToolListParamsSchema` names no cursor field at all — and the two refusals blamed the vendor for
* the wrapper's shape.
*
* IT MATTERED MOST WHERE IT COST MOST. Composio publishes more than {@link WHOLE_LISTING} toolkits,
* so the catalogue refusal fired on the FIRST call every time and an operator opening the app
* picker saw no apps at all — not a truncated directory, none. The tests below are about the rows
* on the SECOND page, because a reader that stops at the first is exactly as wrong as the old
* refusal was and answers far more plausibly.
*/
describe("listings Composio pages, read to the end", () => {
/** One catalogue row, complete, so a test about paging is not also a test about a field. */
const app = (slug: string) => ({
slug,
name: slug.toUpperCase(),
meta: {
description: `The ${slug} app.`,
logo: `https://logo.test/${slug}.png`,
categories: [{ id: "productivity", name: "Productivity" }],
tools_count: 3,
},
});
/** One action row as the raw client hands it over, which is snake_case and unparsed. */
const action = (slug: string) => ({
slug,
description: `Does ${slug}.`,
input_parameters: { type: "object", properties: {} },
tags: ["readOnlyHint"],
version: "20260903_00",
});
test("an app on the catalogue's second page is an app the picker can find", async () => {
const asked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async (query: unknown) => {
asked.push(query);
return (query as { cursor?: string }).cursor === undefined
? { items: [app("slack")], next_cursor: "page_2" }
: { items: [app("gmail")], next_cursor: null };
},
},
}),
() => 1_000_000,
);
// `gmail` is the whole test, and it is the app the operator waiting on this actually typed.
// Under the old refusal this call answered nothing at all; under a pager that stopped at page
// one it answers an app short and says so nowhere.
expect((await broker.listApps()).map((one) => one.slug)).toEqual([
"slack",
"gmail",
]);
// The first request carries no cursor FIELD rather than an undefined one, and the second
// carries the vendor's own word for where it left off.
expect(asked).toEqual([
{ limit: WHOLE_LISTING, sort_by: "usage" },
{ limit: WHOLE_LISTING, sort_by: "usage", cursor: "page_2" },
]);
});
test("an action on the second page is an action the refresh records", async () => {
const asked: unknown[] = [];
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async (query: unknown) => {
asked.push(query);
return (query as { cursor?: string }).cursor === undefined
? { items: [action("GMAIL_FETCH_EMAILS")], next_cursor: "page_2" }
: { items: [action("GMAIL_SEND_EMAIL")], next_cursor: null };
},
},
}),
);
const listed = await actions.listActions("gmail", { limit: WHOLE_LISTING });
expect(listed.map((one) => one.slug)).toEqual([
"GMAIL_FETCH_EMAILS",
"GMAIL_SEND_EMAIL",
]);
// `refreshTools` commits a listing as the complete truth about an app — the write is a delete
// and an insert — so an action left on page two is an action DELETED from `mcp_tools` under a
// refresh that reported success, taking every grant pointing at it.
expect(listed[1]).toEqual({
slug: "GMAIL_SEND_EMAIL",
description: "Does GMAIL_SEND_EMAIL.",
inputParameters: { type: "object", properties: {} },
tags: ["readOnlyHint"],
version: "20260903_00",
});
/*
* THE QUERY IS ASSERTED BECAUSE THREE OF ITS FIELDS ARE THINGS THE WRAPPER USED TO DO FOR US.
* `toolkit_versions` is the SDK's own default, forwarded on every listing it made
* (`@composio/core` 0.18.1, `src/models/Tools.ts:548`), and it decides which `version` each
* action comes back with — the value a later call sends back to Composio. `limit` is the page,
* and its absence is what used to let the vendor apply twenty. And `important` is named
* NOWHERE, deliberately: the wrapper set it to "true" whenever a toolkit query gave no limit
* (`:505-515`), which narrows the answer to a featured subset that nothing in the answer
* declares.
*/
expect(asked).toEqual([
{
toolkit_slug: "gmail",
limit: WHOLE_LISTING,
toolkit_versions: "latest",
},
{
toolkit_slug: "gmail",
limit: WHOLE_LISTING,
toolkit_versions: "latest",
cursor: "page_2",
},
]);
});
test("a catalogue cursor this deployment cannot follow refuses rather than truncates", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => ({ items: [app("slack")], next_cursor: 7 }),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
// A number is a position this deployment cannot express and cannot rule out being real, so it
// is the fault it always was. Coercing it to "7" would be the fragment-read-as-whole mistake
// the pager exists to prevent, wearing a default's clothes.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/sent a number where the cursor to the next page/,
);
expect(refusal.message).toMatch(/Composio's app catalogue/);
});
test("an action cursor this deployment cannot follow refuses rather than truncates", async () => {
const { actions } = buildComposioClient(
fakeVendor({
tools: {
list: async () => ({
items: [action("GMAIL_FETCH_EMAILS")],
next_cursor: { page: 2 },
}),
},
}),
);
const refusal = await failureOf(
actions.listActions("gmail", { limit: WHOLE_LISTING }),
);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/an object/);
expect(refusal.message).toMatch(/gmail's actions/);
});
test("a catalogue page that is not a page of rows refuses", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: { list: async () => ({ items: "gmail" }) },
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
/*
* THE CONTAINER IS THIS FILE'S TO CHECK NOW, WHICH IT WAS NOT BEFORE. The wrapper dereferenced
* every answer on its way out — `response.items.map(...)` — so a malformed envelope died inside
* the vendor's package and reached a reader as the translated `TypeError`. Reading the raw
* client means nothing dereferences it before this file does, and `rows.push(...items)` over a
* string is "string is not iterable" with nothing in it a person can act on.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/sent a string where the rows/);
expect(refusal.message).toMatch(/Composio's app catalogue/);
});
/**
* A BARE LIST IS NOT AN ENVELOPE WITH ITS ROWS MISSING, AND THE ENVELOPE GUARD LET IT THROUGH.
*
* `typeof [] === "object"` and `[] !== null`, so a page that arrived as a bare list satisfied the
* test for being an envelope and fell to the one below it — which reads `answered.items`, finds
* `undefined`, and says "Composio sent nothing where the rows of Composio's app catalogue
* belong". That sentence sends an operator looking at a listing whose rows did not arrive, about
* an answer that contained no listing at all: the shape Composio sent is the finding, and it was
* the one part the refusal did not name. It is also the likeliest of the two shapes — the SDK's
* transformers used to hand bare arrays back, which is exactly what a version drift here would
* look like.
*/
test("a catalogue page that arrived as a bare list is named as one rather than as missing rows", async () => {
const { broker } = buildComposioClient(
fakeVendor({ toolkits: { list: async () => [] } }),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/sent a list where a page of/);
expect(refusal.message).not.toMatch(/where the rows of/);
expect(refusal.message).toMatch(/Composio's app catalogue/);
});
/** The same shape on the other raw listing, whose consequence is a set of tools rather than a page. */
test("an action page that arrived as a bare list is named as one rather than as missing rows", async () => {
const { actions } = buildComposioClient(
fakeVendor({ tools: { list: async () => [] } }),
);
const refusal = await failureOf(
actions.listActions("gmail", { limit: WHOLE_LISTING }),
);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/sent a list where a page of/);
expect(refusal.message).not.toMatch(/where the rows of/);
expect(refusal.message).toMatch(/gmail's actions/);
});
test("an action page that is not a page of rows refuses", async () => {
const { actions } = buildComposioClient(
fakeVendor({ tools: { list: async () => null } }),
);
const refusal = await failureOf(
actions.listActions("gmail", { limit: WHOLE_LISTING }),
);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/gmail's actions/);
});
test("the catalogue stops at the page ceiling rather than reading a listing that never ends", async () => {
let pages = 0;
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => {
pages += 1;
// THE TEST'S OWN STOP, which its sibling over the accounts listing has and this one did
// not. The cursor here is different on every page, so nothing in the fixture ever ends
// the listing — the adapter's ceiling is the only thing that does. Without this throw,
// an adapter that LOST its ceiling does not redden this test: it hangs the whole file
// for ever, which is a suite that never reports rather than a test that fails, and the
// difference matters most in CI where a hang is read as an infrastructure fault.
if (pages > PAGES_BEFORE_REFUSING) {
throw new Error("The paging did not terminate.");
}
return {
items: [app(`app_${pages}`)],
next_cursor: `page_${pages}`,
};
},
},
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
// The number of pages READ and the number the refusal STATES, both against the literal.
expect(pages).toBe(PAGES_BEFORE_REFUSING);
expect(refusal.message).toMatch(
new RegExp(`answered ${PAGES_BEFORE_REFUSING} pages`),
);
expect(refusal.message).toMatch(/Composio's app catalogue/);
});
test("a catalogue row whose metadata is not an object refuses", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => ({
items: [{ slug: "gmail", name: "Gmail", meta: "productivity" }],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
/*
* A GUARANTEE THAT CAME FROM THE WRAPPER AND LEAVES WITH IT. `transformToolkitListResponse`
* built each row's meta itself, spreading it into a fresh literal, so every meta arriving here
* was an object however the wire had spelled it. Nothing does that now, and `meta.description`
* off a string is `undefined` rather than a throw — so the app would have shown no description,
* no logo, no categories and no count, indistinguishable from an app that published none.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/sent a string where gmail's description, logo, categories and action count belong/,
);
});
test("a catalogue row whose categories are not a list refuses", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
list: async () => ({
items: [
{
slug: "gmail",
name: "Gmail",
meta: { categories: "productivity" },
},
],
}),
},
}),
() => 1_000_000,
);
const refusal = await failureOf(broker.listApps());
// The wrapper's `item.meta.categories?.map(...)` died on this one; nothing maps it now, so a
// string would be read as an app that publishes no categories at all.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/sent a string where gmail's categories belong/,
);
});
});
/**
* What an app asks a person to type, read off the vendor rather than written down here.
*
* THE FIXTURES ARE MEASURED ANSWERS RATHER THAN INVENTED ONES. The first is `perplexityai`'s
* `API_KEY` mode as Composio publishes it, down to the `legacy_template_name` this deployment does
* not read — because the value of asking the vendor at all is that the form follows what the app
* actually wants, and a fixture composed of the four fields the mapping happens to touch would
* assert that mapping against a shape no app sends.
*/
describe("the fields an app asks a person to fill in", () => {
test("the fields an app wants come back as the app describes them", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API Key",
description:
"Your secret Perplexity API key, starting with 'pplx-'.",
type: "string",
required: true,
is_secret: true,
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
expect(
await broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "generic_api_key",
label: "API Key",
help: "Your secret Perplexity API key, starting with 'pplx-'.",
required: true,
secret: true,
},
]);
});
test("a field of a type this deployment cannot draw is refused rather than drawn blind", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "cert",
displayName: "Certificate",
type: "file",
required: true,
is_secret: true,
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "mystery", authScheme: "API_KEY" }),
);
/*
* A TEXT BOX DRAWN FOR A FILE IS THE FAILURE THIS PREVENTS: somebody types a path into a box
* labelled Certificate, the connection is made, and the first tool call is what discovers it.
* Every required field measured across the catalogue is a plain string, so this is a guard
* against the vendor changing rather than a routine case.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
/*
* AND IT IS THE TYPE FAULT RATHER THAN ITS TWIN. One guard raises this sentence for two faults
* — a type that is not a string, and a name that did not arrive — and both tests over it
* asserted the clause they SHARE, so neither could tell a correct classification from a wrong
* one. What moves between them is the field position: the type fault names a box that has a
* name, and its twin names one published "under the name nothing".
*/
expectOnlyRefusal(refusal.message, "fieldTypeNotDrawable");
});
test("a field named for the word the connection state uses is refused, not drawn", async () => {
/*
* A BOX WHOSE ANSWER CANNOT BE SENT MUST NOT BE DRAWN, which is the same rule the nameless field
* above is refused under. `connectWithFields` sends `{ status: "ACTIVE", ...values }` — the
* shape the vendor's own `AuthScheme` builder assembles (`@composio/core` 0.18.1,
* `src/models/AuthScheme.ts:84-94`) — so `status` is the protocol's word inside that object and
* not a name a value may travel under. Either answer to a box named that is wrong: sent, it
* replaces the state this deployment is asking Composio to create, and withheld, it is a box
* somebody filled in whose value no app ever reads.
*
* SO THE APP IS REFUSED RATHER THAN PART OF ITS FORM, and the sentence names the field, which is
* the vendor's own text and the only thing an administrator can act on.
*/
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "status",
displayName: "Account status",
type: "string",
required: true,
is_secret: false,
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "drifted", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/status/);
expect(refusal.message).toMatch(/drifted/);
});
test("a name published in both lists is one box, and the required one", async () => {
/*
* THE TWO LISTS ARE JOINED AND A NAME IS NOT A SEAT. `required` and `optional` are published
* separately and were concatenated as they arrived, so an app naming one field in both drew TWO
* boxes labelled the same thing — and whichever the person typed in second is the one that won
* in the submitted values, because a later key overwrites an earlier one in the object the form
* builds. Nothing anywhere says which of the two they filled in.
*
* FIRST SIGHTING KEEPS ITS PLACE, which is the rule `readableConfigs` and `withdrawableAccounts`
* already dedupe identifiers under, and required is read FIRST — so a name in both lists is
* treated as the required one. That is the safe direction: read as optional, a credential the
* app cannot do without becomes a box the connect route lets somebody leave blank.
*/
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API Key",
description: "Your secret key.",
type: "string",
required: true,
is_secret: true,
user_visible: true,
},
],
optional: [
{
name: "generic_api_key",
displayName: "API Key (optional)",
description: "Leave this alone.",
type: "string",
required: false,
is_secret: false,
user_visible: true,
default: "pplx-",
},
],
},
},
},
],
}),
},
}),
);
expect(
await broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "generic_api_key",
label: "API Key",
help: "Your secret key.",
required: true,
secret: true,
},
]);
});
/**
* A ROW THAT IS NOT A ROW IS A VENDOR SHAPE, AND IT WAS WEARING THE SENTENCE FOR AN APP.
*
* Every other container this file opens is tested for being one before a field is read off it —
* the catalogue row, its meta, each category, the action row, the toolkit detail, the mode. The
* field rows were not, and `("generic_api_key").type` is `undefined` rather than a throw, so a row
* that arrived as a string reached the type guard and was refused with "Connecting this app is not
* something this deployment can offer yet" — a verdict about the APP, carrying no remedy at all,
* for an answer whose only fault is a package that has changed shape. The two are not the same
* finding and they are not the same person's to fix.
*/
test("a field row that is not an object is refused as a vendor shape rather than as an app nobody can connect", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: ["generic_api_key"],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
expect(refusal.message).toMatch(/sent a string where/);
expect(refusal.message).not.toMatch(
/not something this deployment can offer yet/,
);
});
/** And the same guard under the row that a `user_visible` read would have reached first. */
test("a field row that arrived as null is refused as a vendor shape too", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [],
optional: [null],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/sent null where/);
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
});
/**
* "NO SUCH MODE" AND "THIS MODE ASKS FOR NOTHING" ARE TWO ANSWERS, AND THEY USED TO BE ONE `[]`.
*
* The scheme handed in is the RECORDED one and is never re-derived — that is the entire point of
* the column — so a mode Composio has stopped publishing for this app is exactly the drift
* recording it anticipates. As an empty form it is invisible: the person presses submit, a
* connection is created carrying no credential at all, Composio answers `ACTIVE` because it does
* not grade what it is given, and the later probe is the first thing that notices. From their end
* it is a box they cannot fill in.
*/
test("a mode this app no longer publishes is refused rather than drawn as an empty form", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
// The app publishes OAuth2 today; the row here was enabled as API_KEY and still says so.
retrieve: async () => ({
auth_config_details: [
{
mode: "OAUTH2",
fields: {
connected_account_initiation: { required: [], optional: [] },
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "linear", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// The app and the RECORDED scheme, because those two are the whole of the finding — and the one
// act that rewrites the recorded scheme, which is an administrator's rather than this person's.
expect(refusal.message).toMatch(/linear/);
expect(refusal.message).toMatch(/API_KEY/);
expect(refusal.message).toMatch(/Plugins page/);
});
/**
* AND "I COULD NOT READ WHAT IT ASKS FOR" IS A THIRD ANSWER, WHICH WAS THE SAME `[]` AS THE
* SECOND.
*
* The recorded mode is found here, so the refusal above never fires. What hangs off that mode is
* then read a step at a time off `unknown` — the mode's `fields`, the initiation block inside it,
* and the two lists of rows inside that — and every one of those steps answered an empty list for
* a shape it could not make sense of. An empty list is a sentence: this mode asks a person for
* nothing, which is a true thing some modes say. A `fields` that is not an object is a different
* sentence entirely — Composio moved the shape and the boxes are no longer visible from here —
* and the two arrived at the browser as the same empty form. That form is the one this method's
* own doc says must never be drawn: the person presses submit, `connectWithFields` creates a
* connection carrying no credential at all, Composio answers `ACTIVE` because it does not grade
* what it is given, and the first call made with the account is what discovers anything is wrong.
*
* EVERY STEP IS ITS OWN CASE BECAUSE EVERY STEP IS ITS OWN DRIFT, and a guard on one of them says
* nothing whatever about the three beside it.
*/
test("a published shape this deployment cannot read is refused rather than drawn as an empty form", async () => {
const unreadable = [
// The mode's fields, which stopped being an object at all.
{ mode: "API_KEY", fields: "generic_api_key" },
// The initiation block, which arrived as the list of rows that used to live inside it.
{
mode: "API_KEY",
fields: { connected_account_initiation: ["generic_api_key"] },
},
// And each list of rows on its own, because the required one is the one that stops a form.
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: "generic_api_key",
optional: [],
},
},
},
{
mode: "API_KEY",
fields: {
connected_account_initiation: { required: [], optional: "base_url" },
},
},
];
for (const mode of unreadable) {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({ auth_config_details: [mode] }),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/perplexityai/);
/*
* THE REMEDY IS THE WHOLE OF WHAT SEPARATES THIS FROM THE CASE ABOVE. A shape Composio
* changed is nobody's setting, so what fixes it is an upgrade; a mode the app stopped
* publishing is fixed by an administrator recording the scheme afresh on the Plugins page.
* Handing the second sentence to somebody holding the first sends them to remove and re-add
* an app whose publication never moved, after which the re-add reads the same unreadable
* answer and records the same word.
*/
expect(refusal.message).toMatch(/@composio\/core/);
expect(refusal.message).not.toMatch(/Plugins page/);
}
});
/**
* AND THE SAME DISTINCTION ONE LAYER OUT, WHERE THE WRONG ANSWER WAS A REFUSAL RATHER THAN A FORM.
*
* An `auth_config_details` that is not a list became no modes at all, and no modes means the
* recorded one is not among them — so an unreadable answer reached an administrator wearing the
* sentence about a mode this app has stopped publishing. So did a retrieve that answered
* something which is not a toolkit: `("perplexityai").auth_config_details` is `undefined` rather
* than a throw. Both sent somebody to the Plugins page to remove and re-add an app that publishes
* exactly what it always did.
*/
test("an answer whose modes this deployment cannot read is refused as that rather than as a mode the app dropped", async () => {
for (const answered of [
"perplexityai",
{ auth_config_details: "API_KEY" },
]) {
const { broker } = buildComposioClient(
fakeVendor({ toolkits: { retrieve: async () => answered } }),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "linear", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/linear/);
expect(refusal.message).toMatch(/@composio\/core/);
expect(refusal.message).not.toMatch(/Plugins page/);
}
});
/**
* AND THE NAME IS THE ONE FIELD THAT TRAVELS, WHICH IS WHY IT IS GUARDED LIKE THE TYPE.
*
* `label`, `help` and `default` all pass through `textOf` and are read by a person. The name is
* sent back to Composio verbatim and is the key `connectWithFields` spreads into the connection's
* `val`. Coerced with `String(...)`, this row drew a box literally called "undefined" and then
* submitted whatever was typed into it under that key: a value no app reads, inside a connection
* Composio accepts.
*/
test("a field with no name is refused rather than drawn as a box called undefined", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
displayName: "API Key",
description: "",
type: "string",
required: true,
is_secret: true,
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "nameless", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
// The absence rather than the shared clause, for the reason the type fault above gives: this
// is the half of that one guard that says the box could not be named at all.
expectOnlyRefusal(refusal.message, "fieldNameMissing");
// And never the coercion itself, which is what the form used to be handed.
expect(refusal.message).not.toMatch(/"undefined"/);
});
test("a field Composio marks invisible is not shown", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "internal_tenant",
displayName: "Tenant",
description: "",
type: "string",
required: true,
is_secret: false,
user_visible: false,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
expect(
await broker.connectionFields({
toolkit: "hidden",
authScheme: "API_KEY",
}),
).toEqual([]);
});
test("a default Composio padded arrives in the box without its padding", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [],
optional: [
{
name: "base_url",
displayName: "Base URL",
description: "",
default: " https://api.example.com ",
type: "string",
required: false,
is_secret: false,
user_visible: true,
},
],
},
},
},
],
}),
},
}),
);
/*
* THE GUARD AND THE ANSWER READ THE SAME VALUE, which is what this is about rather than the
* whitespace. The method tested `textOf(row.default)` — which trims — and emitted
* `String(row.default)` — which does not — so a padded default passed a judgement made about
* one string and reached the form as another. What a person then submits is whatever is in the
* box, so the padding would travel on into the connection as part of the value.
*/
expect(
await broker.connectionFields({
toolkit: "padded",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "base_url",
label: "Base URL",
help: "",
required: false,
secret: false,
default: "https://api.example.com",
},
]);
});
/**
* "COMPOSIO NO LONGER PUBLISHES THIS MODE" IS A VERDICT, AND AN UNREADABLE ANSWER DOES NOT
* SUPPORT IT.
*
* The refusal above is a claim about the APP — the scheme recorded at enable time is one Composio
* has since stopped offering — and its remedy is an administrator removing the app and adding it
* again, which rewrites the recorded scheme from what the catalogue says today. Reached out of a
* detail whose shape this deployment could not read, that claim is unfounded and the remedy is
* work that changes nothing: the next answer is the same shape, so the app is removed, re-added,
* and refuses identically. Every shape below is PRESENT and is not what it is declared to be, and
* each one used to arrive as `modes = []`, `mode === undefined`, or an empty form.
*/
const UNREADABLE_DETAILS: { what: string; detail: unknown }[] = [
{ what: "no detail document at all", detail: null },
{ what: "a detail that is not an object", detail: "API_KEY" },
{
what: "auth_config_details that is not a list",
detail: { auth_config_details: "API_KEY" },
},
{
what: "a mode that is not an object",
detail: { auth_config_details: ["API_KEY"] },
},
/*
* THE ONE THAT IS AN OBJECT AND IS STILL UNCLASSIFIABLE, which the shape test above does not
* catch. `{ mode: null, fields: {…} }` is an object and not an array, so it passes that guard,
* and `textOf` then answers null — which never equals a scheme name, so the walk moved on and
* never collected the entry. With nothing in `unreadableModes`, the vendor-shape refusal was
* skipped and the administrator's "Composio no longer publishes a connection of this scheme"
* was reached — over an entry that MAY BE the mode, whose next reading is the same shape.
*/
{
what: "a mode name that is not a name",
detail: {
auth_config_details: [
{
mode: null,
fields: {
connected_account_initiation: { required: [], optional: [] },
},
},
],
},
},
{
what: "fields that are not an object",
detail: { auth_config_details: [{ mode: "API_KEY", fields: "none" }] },
},
{
what: "an initiation section that is not an object",
detail: {
auth_config_details: [
{ mode: "API_KEY", fields: { connected_account_initiation: 7 } },
],
},
},
{
what: "a required list that is not a list",
detail: {
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: "generic_api_key",
optional: [],
},
},
},
],
},
},
{
what: "an optional list that is not a list",
detail: {
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [],
optional: { base_url: "" },
},
},
},
],
},
},
];
for (const shape of UNREADABLE_DETAILS) {
test(`${shape.what} is refused as a shape rather than as a withdrawn mode`, async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: { retrieve: async () => shape.detail },
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "drifted", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/drifted/);
// The remedy is a package upgrade rather than an administrator re-adding the app, because
// removing and adding it again meets the same shape and refuses the same way.
expect(refusal.message).toMatch(/@composio\/core/);
expect(refusal.message).not.toMatch(/no longer publishes/);
});
}
/**
* AND A DRIFTED MODE BESIDE A READABLE ONE TAKES DOWN NEITHER THE FORM NOR THE APP.
*
* CRITERION. Where the wanted mode is present and complete, an entry elsewhere in the list that
* this deployment cannot read is ignored and the form is drawn exactly as it would have been.
*
* REASON. The walk over these entries was a `.map()` that threw, so EVERY entry was validated
* before `.find()` ever selected the mode being asked for. One drifted entry anywhere in the list
* therefore took down a mode that was perfectly readable: an app enabled as `API_KEY` whose
* retrieve answers `[{ mode: "API_KEY", fields: {…complete…} }, "OAUTH2"]` has an intact mode at
* index 0, and everybody pressing Connect on it was blocked permanently — "no form was drawn …
* upgrading @composio/core is what fixes it" — over a mode nobody asked about. Nothing they can
* reach changes the next reading, which is the same shape.
*
* THIS IS THE PARTITION-RATHER-THAN-THROW DISCIPLINE THE FILE ALREADY APPLIES at `readableConfigs`
* and `withdrawableAccounts`, arriving at the one reader that was still eager. The table above is
* the other half and still holds: a list with NO readable wanted mode is still refused as a shape.
*/
test("a mode this deployment cannot read does not block a readable one beside it", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API key",
description: "The key.",
type: "string",
required: true,
is_secret: true,
},
],
optional: [],
},
},
},
// The drift, in a mode nobody on this path asked about.
"OAUTH2",
],
}),
},
}),
);
expect(
await broker.connectionFields({
toolkit: "drifted",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "generic_api_key",
label: "API key",
help: "The key.",
required: true,
secret: true,
},
]);
});
/**
* AND WHERE THE WANTED MODE IS NOT FOUND, THE UNREADABLE ENTRIES DECIDE WHICH REFUSAL IT IS.
*
* "Composio no longer publishes this mode" is a claim about the APP, and its remedy is an
* administrator removing it and adding it again. Beside an entry this deployment could not read,
* that claim is unfounded — one of those entries may BE the mode — and the remedy is work that
* changes nothing, because the next answer is the same shape. So the vendor's remedy wins.
*/
test("a wanted mode missing beside an unreadable entry is a shape refusal, not a withdrawn mode", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [{ mode: "OAUTH2", fields: {} }, "API_KEY"],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "drifted", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/@composio\/core/);
expect(refusal.message).not.toMatch(/no longer publishes/);
});
/**
* A VENDOR BOOLEAN THAT IS NOT A BOOLEAN IS THE ONE STATE `=== true` CANNOT REPORT.
*
* `row.required === true` has three inputs and two answers. An ABSENT flag reading as "optional"
* is the benign default this idiom was chosen for, and it stays. A PRESENT `"true"` reading as
* "optional" is a different fact wearing the same answer: Composio said the field has to be
* filled in, and the form drew a box a person may leave blank.
*
* WHICH IS LOAD-BEARING BECAUSE THE CONNECT ROUTE NOW READS THIS BOOLEAN. The guard that refuses
* a submission omitting a required field asks this field and no other, so a vendor publishing
* `"true"` makes the guard wave through the exact submission it was added to refuse: a
* connection Composio answers `ACTIVE` for with the credential missing out of it.
*
* REFUSED RATHER THAN COERCED, AND THE STRING IS THE ARGUMENT. The drift that publishes `"true"`
* publishes `"false"` on the fields beside it, and `"false"` is a truthy string — so a
* `Boolean(...)` written to rescue this case turns every optional field into a required one and
* stops a person connecting at all. There is no reading of a wrong-shaped flag that is right on
* both halves, which is what every other reader in this file already says about a vendor value it
* cannot read.
*/
test("a required flag Composio sent as a string is refused rather than read as optional", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API Key",
description: "",
type: "string",
required: "true",
is_secret: true,
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
// The shape and never the value, like every other vendor read here.
expect(refusal.message).toMatch(/with a string where/);
expect(refusal.message).toMatch(/has to be filled in/);
expect(refusal.message).toMatch(/@composio\/core/);
});
/**
* AND THE SAME SHAPE ON `is_secret` IS THE OTHER HALF OF ONE BOX'S DESCRIPTION.
*
* Read as a no — which is what `=== true` makes of `"true"` — the box for somebody's API key is
* drawn as ordinary text: typed in plain sight, left on the screen, and offered to whatever the
* browser fills fields with. That is not a smaller failure than the required one, it is a quieter
* one, and it is the same vendor drift arriving one field along.
*/
test("a secret flag Composio sent as a string is refused rather than drawn unmasked", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "generic_api_key",
displayName: "API Key",
description: "",
type: "string",
required: true,
is_secret: "true",
user_visible: true,
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({
toolkit: "perplexityai",
authScheme: "API_KEY",
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/with a string where/);
expect(refusal.message).toMatch(/holds a secret/);
});
/**
* AND THE VISIBILITY FLAG IS THE THIRD, WHOSE DEFAULT POINTS THE OTHER WAY AND WHOSE FAULT DOES
* NOT.
*
* `user_visible !== false` is right about an absent flag — a field Composio says nothing about is
* one to show — and it reads a present `"false"` as "show it" too, which is Composio saying the
* opposite. What that draws is a box for a value Composio fills in itself: a person is asked for
* a tenant id they have no way to know, and the field they leave blank is submitted as an empty
* one.
*/
test("a visibility flag Composio sent as a string is refused rather than read as visible", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [
{
name: "internal_tenant",
displayName: "Tenant",
description: "",
type: "string",
required: true,
is_secret: false,
user_visible: "false",
},
],
optional: [],
},
},
},
],
}),
},
}),
);
const refusal = await failureOf(
broker.connectionFields({ toolkit: "hidden", authScheme: "API_KEY" }),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/with a string where/);
expect(refusal.message).toMatch(/shown to the person filling the form in/);
});
/**
* THE ABSENCES STAY BENIGN, WHICH IS THE HALF THE FIX MUST NOT TAKE WITH IT.
*
* Composio genuinely publishes optional fields with no `required` key, ordinary fields with no
* `is_secret` and visible ones with no `user_visible` — three states that are facts about the
* field rather than faults in the answer. A guard that refused those would refuse most of the
* catalogue, which is the opposite mistake and the reason `=== true` was reasonable to begin
* with.
*/
test("a field publishing none of the three flags is read at its defaults rather than refused", async () => {
const { broker } = buildComposioClient(
fakeVendor({
toolkits: {
retrieve: async () => ({
auth_config_details: [
{
mode: "API_KEY",
fields: {
connected_account_initiation: {
required: [],
optional: [
{
name: "base_url",
displayName: "Base URL",
description: "",
type: "string",
},
],
},
},
},
],
}),
},
}),
);
expect(
await broker.connectionFields({
toolkit: "sparse",
authScheme: "API_KEY",
}),
).toEqual([
{
name: "base_url",
label: "Base URL",
help: "",
required: false,
secret: false,
},
]);
});
});
/**
* THE ONE CALL IN THIS SEAM THAT DROPS THE VENDOR'S ERROR RATHER THAN CARRYING IT.
*
* Every other refusal below this adapter keeps the original as `cause`, deliberately, because the
* object holds the request it was made for and whoever is reading a log rather than a page deserves
* it. On every other call that request is a link mint or a delete. On this one it is somebody's API
* key — so the rule reverses here, and the reversal is worth a test rather than a comment because
* nothing about it is visible in a type or in a passing happy path.
*
* THE LEAK TEST ASKS THE WHOLE THROWN OBJECT AND NOT ITS MESSAGE. `JSON.stringify` of an `Error` is
* `{}` — its fields are non-enumerable — so a check written against that would stay green over a
* `cause` carrying the entire request body, which is exactly the defect this is about. What is
* asserted is that a recognisable secret planted on the vendor's error reaches none of the message,
* the `cause`, or any own property of what escapes, at any depth.
*/
describe("connecting one person with the secret they typed", () => {
/** Shaped like the thing a person pastes into the form, and recognisable wherever it surfaces. */
const TYPED_SECRET = "pplx-LEAK-CANARY-3f9a2c";
/**
* Every string the thrown object carries, its own property names included, at every depth.
*
* `JSON.stringify(error)` answers `{}` for an `Error`, because `message`, `stack` and `cause` are
* all non-enumerable — so a leak test written against it would pass over a `cause` holding the
* whole request. This asks for the own property names at each level and follows whatever hangs
* off them, which is where the secret would be if this call ever carried the vendor's object out.
*/
function everythingCarriedBy(value: unknown, depth = 0): string {
// Deep enough to reach a typed value at the bottom of a request body hanging off a `cause`,
// which is seven levels down from the thrown error and is the whole thing this is looking for.
if (depth > 12) return "";
if (typeof value === "string") return value;
if (typeof value !== "object" || value === null) return String(value);
const held = value as Record<string, unknown>;
return Object.getOwnPropertyNames(held)
.map((name) => `${name}=${everythingCarriedBy(held[name], depth + 1)}`)
.join(" ");
}
/**
* The thrown object as a handler further out would serialize it, hidden fields expanded.
*
* `JSON.stringify(error)` IS `{}` AND THE OBVIOUS FIX IS BARELY BETTER. An `Error`'s `message`,
* `stack` and `cause` are all non-enumerable, so the first form sees none of them — and
* `JSON.stringify(error, Object.getOwnPropertyNames(error))` passes a replacer ARRAY, which is a
* key allow-list applied at EVERY depth: it names the top error's three fields and then filters
* the request body out of the very `cause` it just let through. Measured against the version of
* this adapter that attached the cause, that assertion passed while the key was two levels below
* it. The replacer below expands each error into its own property names instead and lets the
* plain objects under them through whole, which is the serialization this call has to survive.
*/
function serializedWith(error: Error): string {
return JSON.stringify(error, (_key, value: unknown) => {
if (!(value instanceof Error)) return value;
const own = value as unknown as Record<string, unknown>;
return Object.fromEntries(
Object.getOwnPropertyNames(own).map((name) => [name, own[name]]),
);
});
}
test("what the person typed is sent as this connection's state, and the account comes back", async () => {
const asked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: {
create: async (body: unknown) => {
asked.push(body);
return { id: "ca_new", status: "ACTIVE" };
},
},
}),
);
expect(
await broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET, subdomain: "acme" },
}),
).toEqual({ accountId: "ca_new" });
/*
* THE WHOLE BODY, because every part of it decides something. The config is this deployment's
* own rather than whichever row the vendor listed first; the user id is what every later call
* names the account by; and the state is the scheme the form was drawn for with the typed
* values under it, which is the shape `AuthScheme.APIKey` builds (`@composio/core` 0.18.1,
* `src/models/AuthScheme.ts:84-94`) and the one the raw create declares.
*/
expect(asked).toEqual([
{
auth_config: { id: OURS.id },
connection: {
user_id: VENDOR_USER,
state: {
authScheme: "API_KEY",
val: {
status: "ACTIVE",
generic_api_key: TYPED_SECRET,
subdomain: "acme",
},
},
},
},
]);
});
test("a value named status cannot displace the state this call is making", async () => {
/*
* `status` IS THE PROTOCOL'S WORD AND THE VALUES ARE THE VENDOR'S, IN ONE OBJECT. The state this
* call sends is `{ status: "ACTIVE", ...values }` — the shape `AuthScheme.APIKey` builds
* (`@composio/core` 0.18.1, `src/models/AuthScheme.ts:84-94`) — so a value arriving under the
* name `status` is spread OVER the one word in that object that says what is being created. What
* Composio is then told is whatever that value says: an account asked for in a state nobody
* chose, from a request that looks exactly like an ordinary connection.
*
* WHICH IS A GUARD AT THIS SEAM RATHER THAN ONLY AT THE ROUTE ABOVE IT. `connectionFields`
* refuses to draw a box named `status` and the connect route sends only names that list
* published, so nothing reaching here through a form can carry one. This method is callable
* without either, and the word it protects is the one that cannot be re-derived afterwards.
*/
const asked: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: {
create: async (body: unknown) => {
asked.push(body);
return { id: "ca_new", status: "ACTIVE" };
},
},
}),
);
await broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET, status: "INITIALIZING" },
});
expect(asked).toEqual([
{
auth_config: { id: OURS.id },
connection: {
user_id: VENDOR_USER,
state: {
authScheme: "API_KEY",
// The word this deployment sets, whatever arrived beside it under the same name.
val: { generic_api_key: TYPED_SECRET, status: "ACTIVE" },
},
},
},
]);
});
test("a failure on that call carries no vendor object, because the object holds the key", async () => {
/*
* THE VENDOR'S ERROR AS IT ARRIVES FROM A CREATE THAT WAS REFUSED. `@composio/client` hangs the
* response body on `.error` — which is the shallower of the two depths `vendorSentence` reads —
* and the object also carries the request it was made for. On this one call that request is the
* form somebody just filled in, which is why the secret below is planted there and nowhere in
* the sentence: what must survive is Composio's own words, and what must not is everything else.
*/
const raised = Object.assign(
new Error(`400 {"error":{"message":"Invalid credential"}}`),
{
error: {
error: {
message:
"Composio could not use that credential for linear (request req_9f3c).",
},
},
request: {
body: {
auth_config: { id: OURS.id },
connection: {
user_id: "user_1",
state: {
authScheme: "API_KEY",
val: { status: "ACTIVE", generic_api_key: TYPED_SECRET },
},
},
},
},
},
);
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: {
create: async () => {
throw raised;
},
},
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
// Composio's own sentence is what an operator is left with, request id and all, because that is
// the string their dashboard searches on and the only diagnostic this call agrees to keep.
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/req_9f3c/);
// And the object it came out of is gone: not rethrown, not attached, not reachable from what a
// handler further out will serialize.
expect(refusal).not.toBe(raised);
expect(refusal.cause).toBeUndefined();
expect(everythingCarriedBy(refusal)).not.toContain(TYPED_SECRET);
expect(serializedWith(refusal)).not.toContain(TYPED_SECRET);
expect(everythingSaidBy(refusal).join("\n")).not.toContain(TYPED_SECRET);
});
test("a reply with no account id is refused rather than answered as a connection", async () => {
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: { list: configsOf("linear", [OURS]) },
connectedAccounts: { create: async () => ({ status: "ACTIVE" }) },
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
/*
* AN ACCOUNT MAY BE STANDING AT COMPOSIO OVER A REFUSAL HERE, which is the one thing this
* sentence has to carry: the id is what a caller undoes its own work with, so without one there
* is a connection nothing on this deployment can name or take back. The dashboard is where it
* can be seen and removed, and it is the only remedy there is.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/dashboard/);
expect(refusal.message).not.toContain(TYPED_SECRET);
});
test("an app with no config of this deployment's is refused before anything is sent", async () => {
const { broker } = buildComposioClient(
fakeVendor({
// The create is left at `fakeVendor`'s refusal, which is what says the value typed in went
// nowhere: a call that was made would name itself here rather than answering.
authConfigs: { list: configsOf("linear", [BY_HAND]) },
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(NO_CONFIG_REMEDY);
expect(refusal.message).not.toContain(TYPED_SECRET);
});
/**
* THE TWO BELOW ASSERT AN ORDER RATHER THAN A SENTENCE, AND THE ORDER IS THE WHOLE STANCE.
*
* A create that ANSWERS is what makes them able to fail. Left at {@link fakeVendor}'s refusal, an
* implementation that sent the key would throw the double's own error, {@link failureOf} would
* hand back a refusal, and a test asking only "did this refuse" would be green over the exact
* defect — the secret having travelled. So the double here succeeds like the real vendor does on
* a key it has not graded, and what is asserted is that it was never called: `created` empty is
* the statement that the person's credential did not leave this process.
*/
test("a config of ours that is disabled is refused before the key is sent", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
/*
* `configsFor` LISTS WITH `showDisabled: true`, so this row is one this read can meet and
* `ours[0]` cannot tell it from a working config. Composio does not grade a submitted key,
* so a create against it is a request that carries the secret out of this process and comes
* back with an account that cannot work.
*/
authConfigs: {
list: configsOf("linear", [
{ id: "ac_ours", name: "Linear (OpenBot)", status: "DISABLED" },
]),
},
connectedAccounts: {
create: async (body: unknown) => {
created.push(body);
return { id: "ca_new", status: "ACTIVE" };
},
},
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(DISABLED_REMEDY);
expect(refusal.message).not.toMatch(NO_CONFIG_REMEDY);
expect(refusal.message).not.toContain(TYPED_SECRET);
// The point of the test: the refusal arrived before the credential did, not after Composio had
// been handed it and answered.
expect(created).toEqual([]);
});
/**
* AND THE SAME PAIR HERE, BECAUSE THIS METHOD WRITES THE SAME CHAIN AS `authorize`.
*
* The unsettled-status block is duplicated between the two methods rather than shared, so the
* suppression is duplicated with it: a person typing their key into an app whose configs are one
* DISABLED and one PENDING was told only to upgrade a package. Enabling the disabled config in
* Composio's dashboard is what gets their key accepted, and it is not this person's act — which
* is precisely why the sentence has to carry it rather than choose between the two.
*/
test("a disabled config beside an unsettled one is told both remedies here too", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [
{ id: "ac_a", name: "Linear (OpenBot)", status: "DISABLED" },
{ id: "ac_b", name: "Linear (OpenBot)", status: "PENDING" },
]),
},
connectedAccounts: {
create: async (body: unknown) => {
created.push(body);
return { id: "ca_new", status: "ACTIVE" };
},
},
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).toMatch(/neither ENABLED nor DISABLED/);
expect(refusal.message).toMatch(DISABLED_REMEDY);
// And neither clause is worth what it would cost to send the key first.
expect(refusal.message).not.toContain(TYPED_SECRET);
expect(created).toEqual([]);
});
test("a listing this deployment cannot read does not send an administrator round a loop", async () => {
const created: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: configsOf("linear", [{ id: "ac_nameless" }]),
},
connectedAccounts: {
create: async (body: unknown) => {
created.push(body);
return { id: "ca_new", status: "ACTIVE" };
},
},
}),
);
const refusal = await failureOf(
broker.connectWithFields({
account: {
holder: "person",
userId: "user_1",
vendorUserId: VENDOR_USER,
},
toolkit: "linear",
authScheme: "API_KEY",
values: { generic_api_key: TYPED_SECRET },
}),
);
/*
* NOT THE NO-CONFIG REMEDY, which is the finding. The unreadable row may itself BE ours, in
* which case removing the app meets `deleteAuthConfig`'s refusal over the same row and adding
* it again meets `ensureAuthConfig`'s — an administrator sent round a loop that cannot close.
* `authorize` tells the two states apart against this same listing; this path handed out the
* wrong one of the two.
*/
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).not.toMatch(NO_CONFIG_REMEDY);
expect(refusal.message).not.toMatch(DISABLED_REMEDY);
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
expect(refusal.message).not.toContain(TYPED_SECRET);
// And no `cause`, because this method's refusals carry none — see the describe above.
expect(refusal.cause).toBeUndefined();
expect(created).toEqual([]);
});
});
/**
* ENDING ONE ACCOUNT BY ID, WHICH IS A DIFFERENT QUESTION FROM ENDING A PERSON'S ACCESS.
*
* `revoke` above is asked "this person is done with this app" and has to go and find out what that
* means: it lists, it matches, and it deletes everything it found. This one is asked "take back the
* account you just made", and the id it is handed is the whole of the question — so the listing
* that makes the other method correct is, here, both a call nothing needs and a set of accounts
* nobody asked about. The two differ exactly where the local row and Composio have drifted apart,
* which is the state a failed verification is standing in: a connection that works beside the
* attempt that did not. The absence of the listing is therefore asserted rather than assumed.
*/
describe("taking back the one account a verification just made", () => {
test("the delete names that account and asks for the grant behind it, with nothing listed first", async () => {
const deleted: unknown[] = [];
/*
* THE LISTINGS ANSWER RATHER THAN REFUSE, deliberately, and that is what makes this an
* assertion about the method instead of about {@link fakeVendor}. Left at the refusals, a
* sweeping implementation would fail here on a thrown fixture and the failure would read like
* an unrelated vendor error; answering means a sweep gets everything it needs and is caught by
* the one thing that is actually wrong with it — that it went looking at all.
*/
const listed: string[] = [];
const { broker } = buildComposioClient(
fakeVendor({
authConfigs: {
list: async () => {
listed.push("authConfigs.list");
return { items: [OURS] };
},
},
connectedAccounts: {
list: async () => {
listed.push("connectedAccounts.list");
return { items: [{ id: "ca_new" }] };
},
delete: async (id: unknown, params: unknown) => {
deleted.push([id, params]);
return WITHDRAWN;
},
},
}),
);
await broker.revokeAccount("ca_new");
/*
* THE ID AS IT WAS HANDED OVER, AND THE FLAG BESIDE IT. Without `revoke_on_delete` the account
* stops being visible to this deployment and the credential at the far end stands — which is
* worse here than anywhere else in this file, because the secret left live is one somebody
* typed into a form minutes ago that then told them the connection had not been kept.
*/
expect(deleted).toEqual([["ca_new", { revoke_on_delete: true }]]);
expect(listed).toEqual([]);
});
/**
* AND WHAT COMPOSIO ANSWERED IS READ, BECAUSE THE CALLER BRANCHES ON THIS CALL RETURNING CLEANLY.
*
* The await used to drop the reply, so a 200 carrying `success: false` — Composio saying it did
* NOT delete the account and started no revocation — resolved like a withdrawal that happened.
* The verification step above this reads exactly that: a key that fails verification has its
* account withdrawn, and where the WITHDRAWAL fails the row is written unverified so the account
* stays named on a screen and disconnectable. A `success: false` resolving normally takes the
* other branch, writes no row, and leaves a live account holding a credential that nothing in
* this deployment names and nobody can press disconnect on.
*
* THE SENTENCES ARE THIS METHOD'S OWN, which is why they are asserted rather than assumed from
* {@link withdrawalDeclined}. That function's two are written around a toolkit and around
* pressing disconnect again; this call was handed an id, and the second press it would invite is
* a button on no page.
*/
test("the one account's delete answered `success: false` is not a withdrawal", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
// A 200 whose body says the account was not deleted: the flag went out, Composio read the
// request and answered it. This is the vendor declining rather than failing.
delete: async () => ({ success: false }),
},
}),
);
const refusal = await failureOf(broker.revokeAccount("ca_new"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(/success: false/);
// The two facts the caller has to be able to act on: the account stands, and the credential
// behind it was never withdrawn.
expect(refusal.message).toMatch(/still standing at Composio/);
expect(refusal.message).not.toMatch(
/upgrading this deployment's @composio\/core/,
);
});
test("the one account's delete with no verdict in it is not counted as one either", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
/*
* A DOCUMENT THAT ARRIVED WITHOUT ITS VERDICT, which is not the same thing as no document
* at all. `success` is required in the declaration and absent on this wire, and the
* generated client parses the body and hands it over — so the schema's "required" is a
* promise about what Composio means to send rather than a fact about what came.
*/
delete: async () => ({}),
},
}),
);
const refusal = await failureOf(broker.revokeAccount("ca_new"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
/*
* A DIFFERENT SENTENCE FROM THE ONE ABOVE. "Composio said no" is a fact about this account;
* "Composio answered something where its verdict belongs" is a fact about the package, which
* nobody holding an admin page can correct — so it carries the remedy that names the upgrade
* and the other one must not.
*/
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
expect(refusal.message).not.toMatch(/success: false/);
});
/** The same distinction one method over: an answer that is no document is not a missing field. */
test("the one account's withdrawal answered with something that is not a document names the answer", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: { delete: async () => "deleted" },
}),
);
const refusal = await failureOf(broker.revokeAccount("ca_new"));
expect(refusal).toBeInstanceOf(BrokerRefusalError);
expect(refusal.message).not.toMatch(A_CRASH);
expect(refusal.message).toMatch(
/sent a string where its reply to the withdrawal/,
);
expect(refusal.message).not.toMatch(/where its verdict/);
expect(refusal.message).toMatch(
/upgrading this deployment's @composio\/core/,
);
});
/**
* AND NO DOCUMENT AT ALL IS COMPOSIO SAYING IT DID DELETE, which is the opposite mistake and the
* one {@link withdrawalDeclined} was corrected for once already. The installed client resolves a
* 204 to `null` and a JSON reply carrying `content-length: 0` to `undefined`, and neither can be
* a rejection: every `!response.ok` is thrown as an `APIError` before parsing, so an answer
* arriving here at all is Composio having accepted the request. Reading those as "no verdict"
* would turn a completed withdrawal into a failure — which, on this path, has the caller write
* the account's row as unverified over an account that is already gone.
*/
for (const { shape, answer } of [
{ shape: "a 204 carrying no content", answer: null },
{ shape: "a JSON reply of content-length zero", answer: undefined },
]) {
test(`the one account's withdrawal answered with ${shape} is a withdrawal`, async () => {
const deleted: unknown[] = [];
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
delete: async (...call: unknown[]) => {
deleted.push(call);
return answer;
},
},
}),
);
expect(await broker.revokeAccount("ca_new")).toBeUndefined();
// And the flag still went out, so what resolved is a delete that asked for the grant behind
// the account to be withdrawn rather than one that quietly filed the account away.
expect(deleted).toEqual([["ca_new", { revoke_on_delete: true }]]);
});
}
});
/**
* Which account a request is about, named by WHO HOLDS IT rather than by whose request it is.
*
* A deployment's own account and a person's account are each asked for under the `AccountRef`'s
* `vendorUserId` — never under whoever's `userId` happens to be making the request — so the vendor
* id behind a `deployment` holder, `openbot-deployment:<deploymentId>:...`, is what goes out for a
* deployment, and a person's own vendor id goes out for a person. And when a connected-account
* listing comes back, only its published `displayName` is ever read for a name; nothing in that
* listing's tokens is touched or decoded.
*/
describe("accounts named by holder", () => {
const deployment = {
holder: "deployment" as const,
vendorUserId: "openbot-deployment:acme:R1",
};
const person = {
holder: "person" as const,
userId: "user_1",
vendorUserId: VENDOR_USER,
};
/**
* Accounts named the way a wrong question would find them, each carrying a name of its own so
* that the name an answer comes back with says which question was asked.
*/
const NAMED_ELSEWHERE: HeldAccount[] = [
{
row: { id: "ca_person", data: { displayName: "a person's github" } },
toolkit: "github",
},
{
row: { id: "ca_local", data: { displayName: "under the local id" } },
userId: "user_1",
toolkit: "github",
},
{
row: { id: "ca_gmail", data: { displayName: "the deployment's gmail" } },
userId: deployment.vendorUserId,
},
];
test("the deployment's account is asked for under its vendor id, never a person's", async () => {
const { list, asked } = accountListing(
[
{
row: { id: "ca_1" },
userId: deployment.vendorUserId,
toolkit: "github",
},
],
NAMED_ELSEWHERE,
);
const { broker } = buildComposioClient(
fakeVendor({ connectedAccounts: { list } }),
);
expect(
await broker.isConnected({ account: deployment, toolkit: "github" }),
).toBe(true);
expect(asked).toEqual([
expect.objectContaining({ userIds: ["openbot-deployment:acme:R1"] }),
]);
});
/*
* NOT CONNECTED, WHILE THE VENDOR HOLDS A GITHUB ACCOUNT UNDER THIS PERSON'S LOCAL ID. The `false`
* is what tells a question asked under `userId` from one asked under `vendorUserId`: with the two
* spelled alike, as they were here, the assertion on `userIds` could not tell them apart either.
*/
test("a person's account is asked for under their vendor id", async () => {
const { list, asked } = accountListing(
[],
NAMED_ELSEWHERE.filter((account) => account.userId === "user_1"),
);
const { broker } = buildComposioClient(
fakeVendor({ connectedAccounts: { list } }),
);
expect(
await broker.isConnected({ account: person, toolkit: "github" }),
).toBe(false);
expect(asked).toEqual([
expect.objectContaining({ userIds: [VENDOR_USER] }),
]);
});
/*
* THE NAME IS READ OFF THIS PERSON'S ACCOUNT FOR THIS APP, which nothing here asked of a person.
* Every name test below is the deployment's; a person's name read under their local id, or off
* another app's account, is a name a settings page shows them for an account that is not theirs.
*/
test("a person's account name is read off their own account for that app", async () => {
const { list, asked } = accountListing(
[
{
row: { id: "ca_mine", data: { displayName: "[email protected]" } },
toolkit: "github",
},
],
NAMED_ELSEWHERE.slice(1),
);
const { broker } = buildComposioClient(
fakeVendor({ connectedAccounts: { list } }),
);
expect(
await broker.accountName({ account: person, toolkit: "github" }),
).toBe("[email protected]");
expect(asked.map((query) => [query.userIds, query.toolkitSlugs])).toEqual([
[[VENDOR_USER], ["github"]],
]);
});
test("only the display name leaves a listing that carries the account's tokens", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
list: accountListing(
[
{
row: {
id: "ca_1",
data: {
displayName: "acme-bot",
access_token: "gho_SECRET",
refresh_token: "r_SECRET",
client_secret: "cs_SECRET",
id_token: "eyJ.SECRET",
},
state: { val: { access_token: "gho_SECRET" } },
},
userId: deployment.vendorUserId,
toolkit: "github",
},
],
NAMED_ELSEWHERE,
).list,
},
}),
);
const name = await broker.accountName({
account: deployment,
toolkit: "github",
});
expect(name).toBe("acme-bot");
expect(JSON.stringify(name)).not.toMatch(/SECRET/);
});
test("no display name is no name, and nothing is decoded from tokens", async () => {
const { broker } = buildComposioClient(
fakeVendor({
connectedAccounts: {
// Beside a person's NAMED gmail account, so a question asked under anybody but the
// deployment's id answers with somebody's name rather than with none.
list: accountListing(
[
{
row: { id: "ca_1", data: { id_token: "eyJhbGciOi.e30.x" } },
userId: deployment.vendorUserId,
},
],
[
{
row: { id: "ca_p", data: { displayName: "a person's gmail" } },
},
],
).list,
},
}),
);
expect(
await broker.accountName({ account: deployment, toolkit: "gmail" }),
).toBeNull();
});
test("an unconfigured broker names the provider it is missing", () => {
expect(new BrokerUnconfiguredError("arcade", "operator").message).toMatch(
/Arcade/,
);
expect(new BrokerUnconfiguredError("composio", "operator").message).toMatch(
/COMPOSIO_API_KEY/,
);
});
});