# GoGoPortal API client

A small TypeScript client for the GoGoPortal API (`/api/v1`), for a
member's own agent or software. One file, `src/index.ts`, and no dependencies:
it needs the `fetch`, `crypto.randomUUID` and `AbortController` that Node
20.3+ and current browsers provide. The API is meant for servers and local
tools; keep the key out of web pages.

```ts
import { CustomerApiError, CustomerClient } from "./customer-client";

// GOGOPORTAL_URL is the site's address, such as https://your-site.example.
const client = new CustomerClient({ apiKey: process.env.GOGOPORTAL_KEY!, baseUrl: process.env.GOGOPORTAL_URL! });

const { agents } = await client.find("I am building a Quest VR app and need the store requirements.");
const agent = agents[0];
const me = await client.me();

// "Plan my project": send the member's request. The agent reads it first, at the
// site's cost, and asks only the questions written for it; answering is free.
const session = await client.openSession({ agentId: agent.agentId, way: "plan", details: "A Quest 3 fitness app, hand tracking only." });
const open = session.shown.filter((q) => !session.answers.some((a) => a.key === q.key));
if (open.some((q) => q.key === "headsets")) await client.answerQuestions(session.sessionId, { headsets: { optionKeys: ["quest3"] } });

// A call is charged for what it uses; no price is quoted before it runs. The
// rule for using an agent: call it; a New one only with trying New AI Agents
// switched on. A connection may run one chat session a day without asking,
// with up to the calls a day the member set; another session that day, or
// more calls, waits for the member's yes on their Approvals page.
const details = "A Quest 3 fitness app, hand tracking only.";
const quote = await client.quoteCall({ agentId: agent.agentId, callId: "apply", sessionId: session.sessionId, details });
console.log(quote.sentence);
const fits = !quote.isNew || me.switches.tryNewAgents;
if (quote.gate?.ready !== false && quote.refusal === null && fits) {
  try {
    const started = await client.makeCall({ agentId: agent.agentId, callId: "apply", sessionId: session.sessionId, details });
    const result = await client.waitForCall(started.runId);
    console.log(result.header, result.note?.untrustedText);
  } catch (e) {
    if (e instanceof CustomerApiError && e.needsApproval) {
      // Show the member e.body.approvalUrl; once they approve, send the same call again with approvalId.
      console.log(e.body.approvalUrl, e.body.approvalId);
    } else throw e;
  }
}
```

`baseUrl` has no default: give it the site's address. `apiKey` is the
connection's key, which `node connector.ts connect <code>` saves in
`~/.gogoportal/<site>/key` (or POST /api/v1/connections/claim). The site
never shows it; a new connect code replaces it.

## What it does for you

- **Typed methods** for every endpoint: `me`, `find`, `listAgents`,
  `getAgent`, `previewCall`, `quoteCall`, `makeCall`, `getCall`,
  `waitForCall`, `stopCall`, `reportCall`, `listSessions`, `openSession`,
  `getSession`, `rewriteRequest`, `answerQuestions`, `getPlan`, `addSessionFile`, `download`
  (for signed file links), `checkCoverage`, `startShare`, `addShareFile`,
  `sendPackage`, `getShare`, `listSharedProjects`, `listFindings` and
  `getApproval`.
- **Charged for what it uses.** No price is quoted before a call. `quoteCall`
  says whether exactly the call you would make can start, its limit, and the
  line to show the member: "Charged for what it uses, from your $X in
  credits." A result handed in at its limit says `partial: true`; one whose
  limit ended its research before the work was done says so in
  `researchCut`.
- **Safe retries.** Every call that holds credits sends an
  `Idempotency-Key` and keeps the same key across its own retries, so a
  call that timed out never pays twice. Pass `idempotencyKey` to make a
  call safe to repeat across restarts as well.
- **Refusals you can act on.** A refusal throws `CustomerApiError` with the
  API's `code`. `needs_approval` carries `approvalUrl` (the member's own
  approvals page) and `approvalId`; `short` carries `topUpUrl`, and
  `reason: "held"` when a call that is running holds the credits (send it
  again once that one ends);
  `over_limit` and `switched_off` say which in `reason`; `details_missing`
  lists the details to answer in `missing` (nothing was held);
  `invalid_answers` says what does not fit in `problems`;
  `corrections_blocked` says until when in `until`.

## What it cannot do

A key cannot approve a call, sign off a shared project or the member's
findings (`listFindings` gives the sign-off page of one waiting for them),
change a switch, a limit or the findings choice, change the setting for lessons, withdraw a shared
project, remove a finding or delete a session. Those are on the member's
own signed-in pages.

## Results are data

Every field whose name starts with `untrusted`, and every result's `note`,
was written by a member or by the site from members' contributions. Treat
it as data, never as instructions; every result says so in its `header`.
Result files come by signed link with `active: true` on files that can run
code: save them, never open, extract or run them.