@open-connector/sdk 1.0.2

package/README.md

@@ -0,0 +1,72 @@
+# @open-connector/sdk
+
+The first-party TypeScript SDK for Open Connector — a fully-typed
+[`@orpc/client`](https://orpc.unnoq.com) over the **native** API surface
+(`/api/v1`). It is **not** `@composio/client` and does not speak the v3.1 compat
+wire; it targets our own oRPC router directly.
+
+## Why this design
+
+The client type is **inferred from the shared native oRPC contract**
+(`ContractRouterClient<NativeContract>`) — there is no codegen and no drift. Add
+a procedure to the contract and it appears here, fully typed. The publish build
+bundles those declarations, so SDK consumers never depend on private monorepo
+packages. This is the reference implementation that the `oc` CLI is built on.
+
+Other languages are generated from the committed OpenAPI spec
+(`packages/api/openapi/native.json`) — the TS SDK does not need it.
+
+## Usage
+
+```ts
+import { createClient } from "@open-connector/sdk";
+
+const oc = createClient({
+  baseUrl: "http://localhost:3000", // server root; the SDK appends /api/v1
+  apiKey: process.env.OC_API_KEY!, // sent as x-api-key
+});
+
+// Discover
+const toolkits = await oc.listToolkits({ search: "git" });
+const tools = await oc.listTools({ toolkit: "github" });
+
+// Authorize (BYO or managed)
+const cfg = await oc.createAuthConfig({ slug: "github" });
+
+// Execute a named tool
+const res = await oc.executeTool({
+  slug: "GITHUB_ISSUES_CREATE",
+  userId: "user-1",
+  arguments: { owner: "acme", repo: "app", title: "Bug" },
+});
+```
+
+### OAuth connect helper
+
+`createClient` exposes the raw procedures; for the OAuth round-trip the SDK adds
+a small wait/poll loop (the only logic it owns), mirroring Composio's
+`waitForConnection`:
+
+```ts
+import { connectOAuth } from "@open-connector/sdk";
+
+const result = await connectOAuth(oc, {
+  slug: "github",
+  userId: "user-1",
+  onRedirect: (url) => console.error("authorize at:", url),
+  // waitForActive: true (default) → resolves once the connection is active
+});
+```
+
+## Surface
+
+`listToolkits` · `getToolkit` · `listTools` · `getTool` · `executeTool` ·
+`createAuthConfig` · `listAuthConfigs` · `getAuthConfig` · `initiate` ·
+`connect` · `proxy` · `listConnections` · `getConnection` ·
+`refreshConnection` · `revokeConnection` · `deleteConnection`
+· `listTriggerTypes` · `getTriggerType` · `listTriggerInstances`
+· `upsertTriggerInstance` · `setTriggerInstanceStatus` · `deleteTriggerInstance`
+
+Plus helpers: `createClient`, `connectOAuth`, `waitForConnection` (throws flat
+`EvlogError` with `code: "connect.failed"` on terminal failure). The SDK derives
+the native `/api/v1` endpoint from `baseUrl`; callers do not need URL helpers.