@graph8/sdk 0.17.0 → 0.49.0

package/README.md

@@ -129,6 +129,86 @@ export const CTA = () => {
 };
 ```
 
+## Every endpoint: `g8.api` (generated from the contract)
+
+The clients above are the ergonomic layer — hand-written, opinionated, and only
+as complete as someone made them. `g8.api` is the complete one: it is
+**generated from the published OpenAPI contract**, so it covers **every one of
+the 587 Developer API operations**, including surfaces with no hand-written
+client (Appointments, Radar, App Objects, Ad Campaigns, Sandbox, Landing Pages,
+Agent, OpenSearch, ClickHouse and more).
+
+```typescript
+import { g8 } from '@graph8/sdk';
+
+g8.init({ apiKey: process.env.G8_API_KEY });
+
+// Grouped by resource, with full autocomplete on inputs and responses.
+const bookings = await g8.api.appointments.listBookings({ query: { take: 50 } }); // `take`, not `limit` — the types say so
+const competitors = await g8.api.radar.listCompetitors();
+
+// Or address an operation by its stable, published operationId.
+const contacts = await g8.api.call('list_contacts_contacts_get', { query: { limit: 50 } });
+
+// Path, query, headers and body are separate and individually typed.
+const contact = await g8.api.contacts.getContact({ path: { contact_id: 123 } });
+```
+
+Auto-pagination follows `pagination.next_cursor` for you:
+
+```typescript
+import { g8 } from '@graph8/sdk';
+
+for await (const contact of g8.api.paginate('list_contacts_contacts_get', { query: { limit: 100 } })) {
+  console.log(contact);
+}
+```
+
+Every operation carries the side-effect tier and the API-key scope the API
+publishes for it, so an integration can warn a human before a call that spends
+credits or deletes something:
+
+```typescript
+import { g8 } from '@graph8/sdk';
+
+const op = g8.api.operation('list_contacts_contacts_get');
+// { method: 'GET', path: '/api/v1/contacts', tier: 'read', scope: 'contacts:read', ... }
+
+const risky = g8.api.operations().filter((o) => o.tier === 'billable' || o.tier === 'destructive');
+console.log(`${risky.length} operations have side effects worth confirming`);
+```
+
+Contract schemas are available as types under the `G8Contract` namespace:
+
+```typescript
+import type { G8Contract } from '@graph8/sdk';
+
+function fullName(contact: G8Contract.ContactResponse): string {
+  return [contact.first_name, contact.last_name].filter(Boolean).join(' ');
+}
+```
+
+Or let the operation map name them for you, with no import of the schema at all:
+
+```typescript
+import { g8, type ApiOutput } from '@graph8/sdk';
+
+type ContactPage = ApiOutput<'list_contacts_contacts_get'>;
+
+async function firstPage(): Promise<ContactPage> {
+  return g8.api.call('list_contacts_contacts_get', { query: { limit: 25 } });
+}
+```
+
+Two things to know before reaching for it:
+
+- **It returns the raw response envelope.** The hand-written clients unwrap
+  `.data` and rename fields for you; `g8.api` gives you exactly what the
+  contract declares. Prefer the hand-written client where one exists.
+- **It is generated — never hand-edited.** `sdk/js/src/generated/**` is produced
+  by `npm run generate` from `developer-contract/openapi.json`, and CI fails if
+  the two disagree. That is what keeps coverage at 100% as the API grows.
+
 ## Full API Reference
 
 ### Core (write key)