What a module receives

A module root is handed a ModuleClient through props and never builds one, so nothing in module code knows about tokens, proxy prefixes or which host it is running inside.

What a module may call

The last two are optional because the host decides whether to attach them. proxyFetch being present does not promise that a given route exists either — the answer to that is the 404 the route itself gives. A module offers the half of itself that answers and does without the other half; it never asks which modules the deployment installed.

execute (the envelope without the throw), iterate (the async-iterable form of subscribe) and dispose are on the full ChatfuelClient and deliberately not on ModuleClient. The only document type a module ever names is TypedDoc, so the generated shape can change — it has already gone from an AST to a printed string — without a module noticing.

Building one

createChatfuelClient is the factory, and the host app is the only place that calls it.

This is the whole of the shell's factory — the file every scaffolded app carries, and the one place that knows where the proxy is mounted:

export function createAppClient(options: AppClientOptions = {}): ModuleClient {
  const getAuthHeader = async (): Promise<string | undefined> => {
    const value = await options.getAccessToken?.();
    return value ? `Bearer ${value}` : undefined;
  };
  const client = createChatfuelClient({
    url: GRAPHQL_PATH,
    wsUrl: GRAPHQL_PATH,
    token: options.getAccessToken,
    onSessionError: options.onSessionError,
  });
  // Where the session bearer is allowed to go, taken off the same path the
  // client was given. Both are relative here, so in the browser this is the
  // page's own origin and an absolute `basePath` from anywhere else is refused.
  const pinnedOrigin = credentialOrigin(GRAPHQL_PATH);
  return {
    query: client.query,
    mutate: client.mutate,
    subscribe: client.subscribe,
    onReconnect: client.onReconnect,
    uploadFile: (botId, file, fileType, pluginId) =>
      uploadFile({ botId, file, fileType, pluginId, getAuthHeader, pinnedOrigin }),
    proxyFetch: async (path, init) => {
      const auth = await getAuthHeader();
      const headers = new Headers(init?.headers);
      if (auth) headers.set('authorization', auth);
      return fetch(`${PROXY_PREFIX}${path.startsWith('/') ? path : `/${path}`}`, { ...init, headers });
    },
  };
}

Where a credential may go

url and wsUrl are configuration, and a mistake in either is not a failed request — it is a token leaving over a channel everyone on the path can read. Both are judged at construction, so a misconfigured deployment fails at startup rather than on the wire, and url is judged first because it is what the deployment named: wsUrl and the upload path are then held to its origin.

A relative url passes: it inherits the page's origin, and how that page is served is the host's decision. executeHttp checks once more against the header it actually resolved, which is the only place that knows whether a credential is going out.

The token in the browser

token takes a string or a getter, and the getter is resolved per request and per socket connect, so a rotating credential works without rebuilding the client. A getter that answers undefined sends no Authorization header at all.

When the session lapses

onSessionError fires when the gate answers AuthSessionRequired (the session is missing or expired) or AuthTenantForbidden (the caller is not a member of this deployment's tenant). It fires once per lapse — the next successful call re-arms it — and it fires from the HTTP and the WebSocket path alike, so the shell can refresh the session or send the user to sign-in without every module handling it. Neither code means the Chatfuel token needs rotating; that one is Unauthorized, and the whole family is on the errors page.

Timeouts and retries

The default HTTP timeout is 30 000 ms. opts.timeoutMs overrides it for one request, which a handful of Chatfuel mutations need: instagramAccountPublishReel sits on Instagram's transcoder for up to five minutes, and raising the client-wide default so four operations can finish would mean a dead upstream is felt five minutes late everywhere. The timeout signal and your own opts.signal are AbortSignal.any-ed together, so an abort stays an abort.

A response body is read to a cap of 32 MiB and abandoned past it — a declared content-length over the cap never starts. Time bounds how long an answer may take, not how large it may be.

Uploads get a budget shaped to the file instead: 30 seconds plus 20 seconds per MiB, capped at ten minutes, because thirty seconds is generous for a query and not enough for a 25 MiB video on a phone.

Retries only exist when you pass throttle, and the rule is not the same for every failure. A 429 is retried whatever the request was — the server is saying it turned it away before running it, so a repeat cannot double anything, and 429 is always surfaced as an HTTP error rather than an envelope so the throttle can see it. A network failure or a 5xx may mean the request reached Chatfuel, ran, and lost its answer on the way back, so those are retried only when replaying is safe. The client reads that off the document itself: anything that is not a mutation is replayable. A GraphQL error is never retried. Three attempts, backing off from 1 s to 30 s.

Helpers in the same barrel

Everything ~api exports is in content/api-client/src/index.ts; these are the ones worth knowing before you write the same code yourself.