@getunblocked/sdk 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting Started
+
+`@getunblocked/sdk` is a lightweight TypeScript wrapper for the Unblocked Public API. It uses the platform `fetch`, ships as ESM, and has no runtime dependencies.
+
+## Install
+
+```bash
+npm install @getunblocked/sdk
+```
+
+## Create a Client
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+});
+```
+
+The SDK also exports named client aliases:
+
+```ts
+import { Unblocked, UnblockedClient } from "@getunblocked/sdk";
+```
+
+## Research the Connected Context
+
+`client.context.research` runs unified multi-source research and synthesizes an answer with references.
+
+```ts
+const research = await unblocked.context.research({
+  query: "How does the user authentication system work?",
+});
+
+console.log(research.summary);
+for (const source of research.sources) {
+  console.log(source.content);
+  console.log(source.url);
+}
+```
+
+`context.research` resolves to a `ContextResearchResponse` with `summary`, `sources`, and `effort`. Search, query, and get methods resolve to responses carrying a `sources` array.
+
+## Search a Single Source
+
+Use the nested `context.search.*` methods to search one source at a time.
+
+```ts
+const code = await unblocked.context.search.code({
+  query: "rate limiting",
+});
+
+console.log(code.sources.map((source) => source.content));
+```
+
+## Next Steps
+
+- Read [Context](./context.md) for the full research, search, query, and get surface.
+- Read [Authentication](./authentication.md) before using the SDK in automation.
+- Read [Configuration](./configuration.md) for retries, timeouts, custom fetch, and custom base URLs.
+- Read [Agent Frameworks](./agent-frameworks.md) to expose Unblocked as agent tools.

package/docs/low-level-requests.md

@@ -0,0 +1,72 @@
+# Low-Level Requests
+
+Use `request` or `requestRaw` when an endpoint is not yet wrapped by a resource helper or when you need direct response access.
+
+## JSON Request
+
+```ts
+const result = await unblocked.request("POST", "/tools/context/research", {
+  body: {
+    query: "How does auth work?",
+  },
+});
+```
+
+## Request Body
+
+```ts
+const result = await unblocked.request("POST", "/tools/context/search/code", {
+  body: {
+    query: "rate limiting",
+  },
+});
+```
+
+## Raw Response
+
+`requestRaw` returns both the parsed value and the original `Response`.
+
+```ts
+const { value, response, requestId } = await unblocked.requestRaw(
+  "POST",
+  "/tools/context/research",
+  {
+    body: { query: "How does auth work?" },
+  },
+);
+
+console.log(response.headers.get("x-request-id"));
+console.log(requestId);
+console.log(value);
+```
+
+## Request Options
+
+Low-level requests accept the same options as resource methods:
+
+```ts
+await unblocked.request("POST", "/tools/context/research", {
+  body: { query: "How does auth work?" },
+  timeoutMs: 10_000,
+  maxRetries: 1,
+  headers: {
+    "X-Request-Id": requestId,
+  },
+});
+```
+
+## Type Parameters
+
+Use a type parameter when you know the response shape.
+
+```ts
+import type { ContextResearchResponse } from "@getunblocked/sdk";
+
+const result = await unblocked.request<ContextResearchResponse>(
+  "POST",
+  "/tools/context/research",
+  {
+    body: { query: "How does auth work?" },
+  },
+);
+```

package/docs/pagination.md

@@ -0,0 +1,29 @@
+# Pagination
+
+Context methods do not paginate. They return their response directly: search, query, and get methods return `sources`, and `research` returns `summary`, `sources`, and `effort`.
+
+For list-style endpoints you reach through low-level `request` or `requestRaw`, the SDK does not return a page object or parsed cursors. Use `requestRaw` when you need the raw `Response`, then parse the `Link` header yourself.
+
+## Manual Cursor Pagination
+
+The SDK does not parse cursors for you on the low-level path, so read the raw `Link` header from the `Response`, find its `rel="next"` URL, and extract the `after` cursor yourself. Keep the request path relative and pass the cursor through the `query` option — do not pass the full `Link` URL as the path.
+
+```ts
+let after: string | undefined;
+
+do {
+  const { value, response } = await unblocked.requestRaw("GET", "/some/list", {
+    query: { limit: 100, after },
+  });
+
+  for (const item of value.items) {
+    console.log(item);
+  }
+
+  const link = response.headers.get("link");
+  const match = link?.match(/<([^>]+)>\s*;\s*rel="next"/);
+  after = match ? new URL(match[1]).searchParams.get("after") ?? undefined : undefined;
+} while (after);
+```
+
+`requestRaw` exposes the raw `Response` including its `Link` header, but it does not expose parsed cursors — callers parse the header themselves to drive cursor pagination against arbitrary endpoints.

package/docs/release.md

@@ -0,0 +1,73 @@
+# Release Guide
+
+The SDK is currently distributed from this private GitHub repo (not npm). A
+release is a git tag `vX.Y.Z`; consumers install it over SSH with
+`bun add git+ssh://git@github.com/unblocked/unblocked-typescript-sdk.git#vX.Y.Z`.
+
+The compiled `dist/` is committed to the repo, so installs need no build step
+and no devDependencies. (bun does not run a dependency's `prepare` script or
+install its devDependencies, so build-on-install is not an option.) This means
+**every release must ship a fresh `dist/`** — the `version` script below
+rebuilds and stages it automatically, and CI fails if a commit's `dist/` is
+stale.
+
+## Versioning
+
+Use semantic versioning:
+
+- Patch for bug fixes and documentation-only corrections.
+- Minor for additive API features.
+- Major for breaking API or runtime support changes.
+
+`package.json` is the single source of truth for the version. `npm run build`
+syncs it into `src/version.ts` (which feeds the `User-Agent` header), so the two
+never drift.
+
+## Preflight
+
+```bash
+npm install
+npm test          # builds, then runs the test suite
+npm run typecheck
+```
+
+## Cut the release
+
+`npm version` bumps `package.json`, runs the `version` hook (which rebuilds
+`dist/`, syncs `src/version.ts`, and stages both), then creates the commit and
+tag:
+
+```bash
+npm version minor      # or: patch | major
+git push --follow-tags
+```
+
+Pushing the `vX.Y.Z` tag triggers the release workflow (`.github/workflows/release.yml`),
+which builds, tests, and creates a GitHub Release.
+
+## Release notes
+
+Include:
+
+- New API methods or types.
+- Behavior changes in retries, timeouts, auth, or pagination.
+- Deprecated or removed exports.
+- Required user action.
+
+## Post-release check
+
+Install the tag into a clean project and verify it builds and imports:
+
+```bash
+bun add git+ssh://git@github.com/unblocked/unblocked-typescript-sdk.git#vX.Y.Z
+node -e "import('@getunblocked/sdk').then((m) => console.log(Boolean(m.default), m.VERSION))"
+```
+
+## Publishing to npm (future)
+
+When ready to publish to the registry, the package is already configured for it
+(`files`, `exports`, `types`, and a `prepare` build). The flow becomes:
+
+```bash
+npm publish --access public
+```

package/docs/runtime-and-packaging.md

@@ -0,0 +1,57 @@
+# Runtime and Packaging
+
+## Runtime Support
+
+The SDK is intended for:
+
+- Node.js 18 and newer
+- Worker and edge runtimes with `fetch`
+- TypeScript agent harnesses that execute ESM modules
+
+The SDK requires:
+
+- `fetch`
+- `Headers`
+- `Response`
+- `AbortController` for request timeouts and cancellation
+
+## ESM Package
+
+The package is ESM only.
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+```
+
+CommonJS consumers should use dynamic import:
+
+```js
+const { default: Unblocked } = await import("@getunblocked/sdk");
+```
+
+## Package Contents
+
+The package allowlist includes:
+
+- `dist`
+- `docs`
+- `examples`
+- `README.md`
+- `LICENSE`
+
+Source TypeScript is compiled into `dist` before packing.
+
+## No Runtime Dependencies
+
+The SDK intentionally has no runtime dependencies. TypeScript is a development dependency only.
+
+## Custom Fetch
+
+Pass a custom `fetch` when running in a test harness or runtime with a non-global fetch implementation.
+
+```ts
+const unblocked = new Unblocked({
+  apiKey,
+  fetch: customFetch,
+});
+```

package/docs/typescript.md

@@ -0,0 +1,102 @@
+# TypeScript Guide
+
+The SDK exports runtime clients and type-only helpers from the package root.
+
+## Client Imports
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+import { UnblockedClient, Unblocked as NamedUnblocked } from "@getunblocked/sdk";
+```
+
+## Context Types
+
+```ts
+import type {
+  ContextSearchEffort,
+  ContextSearchSource,
+  ContextSearchSourceType,
+  ContextSearchRequest,
+  ContextSearchResponse,
+  ContextResearchRequest,
+  ContextResearchResponse,
+  ContextQueryIssuesRequest,
+  ContextQueryPrsRequest,
+  ContextQueryResponse,
+  ContextGetUrlsRequest,
+  ContextGetRulesRequest,
+  ContextGetResponse,
+} from "@getunblocked/sdk";
+```
+
+## Working With Results
+
+`client.context.research` resolves to `ContextResearchResponse` (`summary`, `sources`, `effort`). Search, query, and get methods resolve to responses carrying a `sources` array of `ContextSearchSource`, each with a `content` string and optional `title`, `url`, `sourceType`, and `provider`.
+
+```ts
+const result: ContextResearchResponse = await unblocked.context.research({
+  query: "How does auth work?",
+});
+
+console.log(result.summary);
+result.sources.map((source: ContextSearchSource) => source.content);
+```
+
+`ContextSearchEffort` is the shared `"low" | "medium" | "high"` union accepted by the research `effort` field.
+
+## Request Types
+
+```ts
+import type {
+  ApiKey,
+  TokenProvider,
+  UnblockedClientOptions,
+  UnblockedRequestOptions,
+  RequestOptions,
+  JsonRequestOptions,
+  RawResponse,
+} from "@getunblocked/sdk";
+```
+
+## Public API Contract Types
+
+`PublicApiSchemas` mirrors the component schemas from the public OpenAPI contract.
+Use it when you need the raw schema-level type.
+
+```ts
+import type { PublicApiSchemas } from "@getunblocked/sdk";
+
+type ContractTool = PublicApiSchemas["Tool"];
+```
+
+SDK method input types can be stricter than the shared schema when an operation
+rejects missing fields. For example, `ContextResearchRequest` requires `query`,
+which the research endpoint rejects when missing.
+
+## Exact Optional Properties
+
+The SDK is built with `exactOptionalPropertyTypes`. Prefer omitting optional fields instead of setting them to `undefined`.
+
+```ts
+const request: ContextResearchRequest = {
+  query: "How does auth work?",
+};
+```
+
+Avoid:
+
+```ts
+const request = {
+  query: "How does auth work?",
+  effort: undefined,
+};
+```
+
+## Type-Only Imports
+
+Use `import type` for SDK types to keep emitted JavaScript small.
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+import type { ContextResearchResponse } from "@getunblocked/sdk";
+```

package/examples/context-research-tool.ts

@@ -0,0 +1,10 @@
+import { createUnblockedTools, unblockedToolSchemas } from "@getunblocked/sdk";
+
+const tools = createUnblockedTools({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+});
+
+export const research = {
+  ...unblockedToolSchemas.research,
+  execute: tools.research,
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@getunblocked/sdk",
+  "version": "0.1.0",
+  "description": "Lightweight TypeScript SDK for the Unblocked Public API.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Unblocked",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unblocked/unblocked-typescript-sdk.git"
+  },
+  "homepage": "https://docs.getunblocked.com/api-reference/quickstart",
+  "bugs": {
+    "url": "https://github.com/unblocked/unblocked-typescript-sdk/issues"
+  },
+  "keywords": [
+    "unblocked",
+    "sdk",
+    "typescript",
+    "agents",
+    "ai"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "docs",
+    "examples/quickstart.mjs",
+    "examples/context-research-tool.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "node scripts/sync-version.mjs && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "version": "npm run build && git add dist src/version.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}