@planescrm/sdk 0.2.0

package/README.md

@@ -0,0 +1,155 @@
+# @planes/sdk
+
+TypeScript SDK for the [Planes CRM](https://planescrm.com) platform — a typed API
+client, an ergonomic webhook router, OAuth helpers, and an action-handler server
+for building agents.
+
+> **Not yet published.** `@planes/sdk` is currently a private workspace package —
+> it is **not** on npm. Consume it from within this monorepo as a workspace
+> dependency (`"@planes/sdk": "workspace:*"`), or request access from the Planes
+> team. The `npm install @planes/sdk` examples below describe the intended
+> published surface once publishing is enabled.
+
+## Client
+
+`PlanesClient` is a typed client over the `/api/v1` REST surface. It accepts
+exactly **one** authentication mode.
+
+```ts
+import { PlanesClient } from '@planes/sdk';
+
+// 1. A pre-obtained OAuth access token (not auto-refreshed).
+const client = new PlanesClient({ accessToken: 'tok_...' });
+
+// 2. A pk_live_ API key.
+const client = new PlanesClient({ apiKey: 'pk_live_...' });
+
+// 3. OAuth-managed — the client obtains and refreshes access tokens itself,
+//    persisting them through a TokenStorage (in-memory by default).
+const client = new PlanesClient({
+  clientId: process.env.PLANES_CLIENT_ID!,
+  clientSecret: process.env.PLANES_CLIENT_SECRET!,
+});
+
+const { data, total } = await client.opportunities.list({ page: 1, limit: 20 });
+const opp = await client.opportunities.get('opp_123');
+```
+
+Resources: `opportunities`, `customers`, `properties`, `calendarEvents`,
+`contracts`, `jobs`, `estimates`, `invoices`, `inventory`.
+
+### Errors
+
+Every failure throws a subclass of `PlanesError`, each carrying `status` and
+`code`:
+
+```ts
+import { PlanesError, RateLimitError, ValidationError } from '@planes/sdk';
+
+try {
+  await client.opportunities.get('missing');
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    await sleep(err.retryAfter * 1000); // seconds
+  } else if (err instanceof ValidationError) {
+    console.error(err.fieldErrors); // [{ field, message }]
+  } else if (err instanceof PlanesError) {
+    console.error(err.status, err.code, err.message);
+  }
+}
+```
+
+## Webhooks
+
+`client.webhooks` is an ergonomic router over the signed webhook envelope. Handlers
+subscribe to a `"{entity_type}.{event_type}"` key, an entity wildcard
+`"{entity_type}.*"`, or the global wildcard `"*"`. It holds no auth — the signing
+secret is supplied per `process()` call — so wire it into your own HTTP handler.
+
+```ts
+client.webhooks
+  .on('opportunity.created', (d) => console.log(d.event.snapshot))
+  .on('opportunity.*', (d) => audit(d))
+  .on('*', (d) => metrics.count(d.event.entity_type));
+
+// inside your POST route (Express-style):
+app.post('/webhooks/planes', async (req, res) => {
+  try {
+    await client.webhooks.process({
+      body: req.rawBody, // the verbatim request body string
+      signature: req.header('X-Planes-Signature')!,
+      secret: process.env.PLANES_WEBHOOK_SECRET!,
+    });
+    res.sendStatus(204);
+  } catch {
+    res.sendStatus(400); // signature verification failed
+  }
+});
+```
+
+## OAuth (authorization-code flow)
+
+Use the OAuth helpers to drive the login redirect and exchange the returned code
+for tokens.
+
+```ts
+import { buildAuthorizeUrl, exchangeCode } from '@planes/sdk';
+
+const baseUrl = 'https://api.planescrm.com/api/v1';
+
+// 1. Redirect the user to the authorization URL.
+const authorizeUrl = buildAuthorizeUrl({
+  baseUrl,
+  clientId: process.env.PLANES_CLIENT_ID!,
+  redirectUri: 'https://your.app/oauth/callback',
+  scopes: ['opportunities:read', 'opportunities:write'],
+});
+
+// 2. In your callback handler, exchange the code for tokens.
+const tokens = await exchangeCode({
+  baseUrl,
+  clientId: process.env.PLANES_CLIENT_ID!,
+  clientSecret: process.env.PLANES_CLIENT_SECRET!,
+  code: req.query.code as string,
+  redirectUri: 'https://your.app/oauth/callback',
+});
+
+// 3. Seed an OAuth-managed client so refreshes happen automatically.
+import { PlanesClient, MemoryTokenStorage } from '@planes/sdk';
+
+const client = new PlanesClient({
+  clientId: process.env.PLANES_CLIENT_ID!,
+  clientSecret: process.env.PLANES_CLIENT_SECRET!,
+  tokenStorage: new MemoryTokenStorage({
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    expiresAt: Date.now() + tokens.expires_in * 1000,
+  }),
+});
+```
+
+## Agents (action handlers)
+
+Build an agent HTTP server that receives platform action requests. `createAgentApp()`
+gives a chainable builder; call `registerAction(type, handler)` per action and
+`listen()` to start.
+
+```ts
+import { createAgentApp } from '@planes/sdk';
+
+createAgentApp()
+  .registerAction('enrich-opportunity', async (ctx) => {
+    // ctx is the flattened ActionContext: action_type, entity_type,
+    // entity_id, tenant_id, data, stage, metadata, callback_token, ...
+    const enriched = await enrich(ctx.entity_id);
+    return { status: 'completed', output: { enriched } };
+  })
+  .registerAction('send-welcome-email', async (ctx) => {
+    await sendEmail(ctx.data);
+    return { status: 'completed', output: { sent: true } };
+  })
+  .listen({ port: 3000, path: '/actions' });
+```
+
+The handler's returned `ActionResult` is serialized straight back as the HTTP
+response — which is exactly how the platform's external-agent handler consumes it.