Frontend integrations

fs.frontendIntegration() declares a narrow edge proxy for a browser-facing third-party call. Use it when the operation is small and declarative; use your own backend for domain workflows, arbitrary proxying, or durable processing.

import * as fs from "@farthershore/business";
fs.backend("api");
const requests = fs.requests();

const account = fs.route("/v1/account", { get: {} });

const invitations = fs.frontendIntegration("invitations", {
  upstream: "https://api.example.com",
  request: {
    operations: [
      {
        method: "POST",
        path: "/v1/invitations",
        headers: ["x-api-version"],
        body: { kind: "json", maxBytes: 16_384 },
      },
    ],
  },
  injection: {
    secretRef: "INVITATIONS_API_KEY",
    location: "header",
    name: "authorization",
    template: "Bearer {value}",
  },
  response: {
    kind: "json",
    contentTypes: ["application/json"],
    maxBytes: 65_536,
    jsonPointers: ["/id", "/status"],
    responseHeaders: ["x-request-id"],
  },
});

fs.plan("pro", {
  kind: fs.plan.kind.flat,
  price: fs.money.usd(49).monthly(),
  grants: [account, invitations],
  limits: [requests.perMinute(600)],
});

export default fs.business();

Every request and response field is an allowlist. The integration above can call one method/path, accept one browser-provided header and a bounded JSON body, and return only two JSON pointers plus one safe response header.

Secret names, not secret values#

secretRef is an uppercase variable name. The value is platform-owned, encrypted operational state and is delivered only at runtime.

printf '%s' "$INVITATIONS_API_KEY" | \
  farthershore variables set <business> INVITATIONS_API_KEY --idempotency-key <persisted-variables-set-attempt-key>

The contract cannot contain the secret value. The upstream must be a public, bare HTTPS origin; userinfo, private hosts, arbitrary ports, query strings, and fragments are rejected. Browser-controlled headers cannot overlap the injected credential or unsafe hop-by-hop headers.

A granted integration can apply in an environment only once the secret it references has been published to the edge for that environment. A public (FS_PUBLIC_) variable is baked into the bundle, not injected at the edge, so it is never an integration's injection secret.

Plan access#

An integration is reachable only when the caller's compiled plan grants its ref. Declaring it alone is inert. Like route grants, the compiled integration policy is versioned with the subscriber cohort, so narrowing an existing operation is a contract change that must be previewed.

No subscriber economics#

Frontend integrations are platform operations, not customer-billable route usage. Their type rejects route economics and resource effects such as costs, reports, usagePolicy, creates, and deletes. If a third-party call should consume a subscriber meter, put the workflow behind a declared backend route instead.

Response projection#

The edge buffers a bounded response, validates its content type, and constructs a new JSON result from the allowed pointers. It does not blindly proxy the upstream body or headers. Missing pointers are omitted. Oversized or wrong-content-type responses fail closed.

This boundary prevents a provider from unexpectedly widening the data exposed to browser code. Keep projections minimal and test upstream error responses as well as success responses.

Browser use#

The frontend SDK calls the integration through the business origin. Browser code never receives the upstream credential, injection rule, or decrypted secret. See Variables for the frontend call and error handling surface.