@phantomagent/application-client

Reference TypeScript client for Phantom Connected Application API v1.

Contract source of truth (api repo): CONNECTED_APPLICATION_API_V1.md

The SDK implements the contract — it is not the platform specification.

Install (integrations workspace)

cd integrations
npm install
npm run build -w @phantomagent/application-client

Quick start

import { createApplicationClient } from '@phantomagent/application-client';

const client = createApplicationClient({
  baseUrl: process.env.PHANTOM_API_URL!,
  clientId: process.env.PHANTOM_APPLICATION_CLIENT_ID!,
  clientSecret: process.env.PHANTOM_APPLICATION_CLIENT_SECRET!,
  source: 'my-front-door',
});

await client.authenticate();
const health = await client.health();
const caps = await client.capabilities();
const run = await client.execute({ goal: 'Summarize open PRs' });
const result = await client.pollRun(run.run_id, { wait: true });
console.log(result.summary);

API surface (v1 — intentionally boring)

| Method | Endpoint | |--------|----------| | authenticate() | POST /v1/auth/application/token | | health() | GET /v1/applications/me | | capabilities() | GET /v1/applications/me/capabilities | | execute(input) | POST /v1/execute/run-task | | getRun(runId) | GET /v1/execute/:id/run | | pollRun(runId, opts?) | GET /v1/execute/:id/run (wait when opts.wait) |

Conformance

npm run verify:conformance -w @phantomagent/application-client
# auth + capabilities only:
CONFORMANCE_SKIP_EXECUTE=1 npm run verify:conformance -w @phantomagent/application-client

Tests

npm test -w @phantomagent/application-client

Unit tests mock fetch against contract fixtures — no staging required.

Non-goals

• npm publish (until Paperclip server cutover gate)
• Legacy CustomerService.apiKey for production Connected Applications