@getunblocked/sdk 0.1.0

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SDK version. Keep in sync with the `version` field in package.json when
+ * cutting a release; it is sent on the User-Agent header for telemetry.
+ */
+export declare const VERSION = "0.1.0";
+/**
+ * Builds the User-Agent value sent on every request, e.g.
+ * `@getunblocked/sdk/0.1.0 node/20.11.0`. The runtime suffix is best-effort.
+ *
+ * Browsers treat User-Agent as a forbidden header name and silently drop it,
+ * which is harmless: the backend only logs the value for debugging.
+ */
+export declare function getUserAgent(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAQrC"}

package/dist/version.js

@@ -0,0 +1,22 @@
+/**
+ * SDK version. Keep in sync with the `version` field in package.json when
+ * cutting a release; it is sent on the User-Agent header for telemetry.
+ */
+export const VERSION = "0.1.0";
+/**
+ * Builds the User-Agent value sent on every request, e.g.
+ * `@getunblocked/sdk/0.1.0 node/20.11.0`. The runtime suffix is best-effort.
+ *
+ * Browsers treat User-Agent as a forbidden header name and silently drop it,
+ * which is harmless: the backend only logs the value for debugging.
+ */
+export function getUserAgent() {
+    const parts = [`@getunblocked/sdk/${VERSION}`];
+    const nodeVersion = globalThis.process?.versions
+        ?.node;
+    if (nodeVersion) {
+        parts.push(`node/${nodeVersion}`);
+    }
+    return parts.join(" ");
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,KAAK,GAAG,CAAC,qBAAqB,OAAO,EAAE,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAI,UAA6D,CAAC,OAAO,EAAE,QAAQ;QAClG,EAAE,IAAI,CAAC;IACT,IAAI,WAAW,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,QAAQ,WAAW,EAAE,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/docs/README.md

@@ -0,0 +1,28 @@
+# Documentation
+
+This directory contains the SDK documentation for people installing, integrating, and maintaining `@getunblocked/sdk`.
+
+## Start Here
+
+- [Getting Started](./getting-started.md) - install the package and make the first API calls.
+- [Authentication](./authentication.md) - use Personal Access Tokens, Team Access Tokens, environment variables, and token providers.
+- [Configuration](./configuration.md) - configure base URLs, fetch, headers, timeouts, and retries.
+
+## API Guides
+
+- [Context](./context.md) - research, search, query, and fetch context from the connected engine.
+- [Pagination](./pagination.md) - parse Link headers manually when using low-level list requests.
+- [Low-Level Requests](./low-level-requests.md) - call API paths that do not yet have first-class helpers.
+
+## Integration Guides
+
+- [Agent Frameworks](./agent-frameworks.md) - adapt the SDK to TypeScript agent tool systems.
+- [Runtime and Packaging](./runtime-and-packaging.md) - supported runtimes and package publishing behavior.
+- [TypeScript Guide](./typescript.md) - exported types and recommended typing patterns.
+
+## Operations
+
+- [Errors and Retries](./errors-and-retries.md) - handle API errors, timeouts, and retry behavior.
+- [Contributing](./contributing.md) - local development workflow for this SDK.
+- [Release Guide](./release.md) - versioning and publishing checklist.
+- [API Design Notes](./api-design.md) - rationale behind the public interface.

package/docs/agent-frameworks.md

@@ -0,0 +1,84 @@
+# Agent Frameworks
+
+The SDK is designed to be adapted into TypeScript-first agent frameworks without taking a runtime dependency on those frameworks.
+
+## Built-In Tool Helpers
+
+```ts
+import {
+  createUnblockedTools,
+  unblockedToolSchemas,
+} from "@getunblocked/sdk";
+
+const tools = createUnblockedTools({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+});
+
+export const research = {
+  ...unblockedToolSchemas.research,
+  execute: tools.research,
+};
+```
+
+The same pattern works for frameworks that expect a schema plus an `execute` function. If a framework uses a different naming convention, wrap the `tools.research` function in that framework's tool registration API.
+
+## Available Tool Functions
+
+`createUnblockedTools` returns one function per context method, and `unblockedToolSchemas` exposes a matching JSON-schema descriptor for each:
+
+| Function | Purpose |
+| --- | --- |
+| `research` | Unified multi-source research that synthesizes an answer with references. |
+| `searchCode` | Search the connected codebase. |
+| `searchPrs` | Search pull requests. |
+| `searchIssues` | Search issues. |
+| `searchDocumentation` | Search connected documentation. |
+| `searchMessages` | Search connected messages and conversations. |
+| `queryIssues` | Query issues scoped by projects and/or user. |
+| `queryPrs` | Query pull requests scoped by projects and/or user. |
+| `getUrls` | Fetch and summarize the content of specific URLs. |
+| `getRules` | Get coding rules and conventions for a repository. |
+
+`research` resolves to a `ContextResearchResponse` (`summary`, `sources`, `effort`). Search, query, and get functions resolve to responses carrying a `sources` array.
+
+```ts
+const research = await tools.research({
+  query: "Where is rate limiting implemented?",
+  effort: "high",
+});
+
+console.log(research.summary);
+for (const source of research.sources) {
+  console.log(source.content, source.url);
+}
+
+const code = await tools.searchCode({ query: "rate limiter middleware" });
+console.log(code.sources.map((source) => source.content));
+```
+
+## Custom Tool Names
+
+Frameworks often prefer short action names. Keep the SDK call hidden inside a small adapter.
+
+```ts
+export const searchCodebaseKnowledge = {
+  description: "Ask Unblocked about the connected codebase.",
+  parameters: unblockedToolSchemas.research.parameters,
+  execute: tools.research,
+};
+```
+
+## Recommended Agent Instructions
+
+When exposing `research` to an agent, give the agent guidance about when to call it:
+
+```md
+Use research when you need repository, docs, issue, pull request, or team-context information that is not present in the current prompt or local files.
+Prefer specific questions. Include relevant file paths, symbol names, error messages, or URLs when available.
+```
+
+## Example Module
+
+See [`../examples/context-research-tool.ts`](../examples/context-research-tool.ts).
+
+For a complete local Flue demo that shows implementation preflight and bug triage with organizational memory, see [`../examples/flue-bug-triage`](../examples/flue-bug-triage/README.md). For a deployable Eve GitHub-App-webhook agent that makes Unblocked context a required PR-triage step, see [`../examples/eve-pr-triage`](../examples/eve-pr-triage/README.md).

package/docs/api-design.md

@@ -0,0 +1,53 @@
+# API Design Notes
+
+The SDK intentionally exposes two layers:
+
+1. Resource clients for normal application and agent-framework use:
+   `unblocked.context` and its nested `search`, `query`, and `get` groups.
+2. A low-level `unblocked.request()` escape hatch for early adopters who need a
+   new endpoint before a first-class wrapper exists.
+
+## Principles
+
+- Keep the primary client small and branded. `new Unblocked()` is the recommended
+  entry point, while `UnblockedClient` remains available for callers who prefer a
+  descriptive class name.
+- Model the public API's resources directly, but hide fetch details, bearer-token
+  headers, retry timing, response parsing, and link-header parsing.
+- Prefer object parameters for request bodies and option bags so future fields can
+  be added without positional-argument churn.
+- Make invalid calls harder to write. Context inputs require the fields the API
+  needs, such as `query` on research and search or `urls` on `get.urls`.
+- Keep retries conservative. Only replay idempotent methods by default.
+- Keep package boundaries explicit through `exports`, generated declarations, and
+  a narrow `files` allowlist.
+- Avoid runtime dependencies so the package works in Node, edge runtimes, and
+  TypeScript agent harnesses.
+
+## Chosen Surface
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+  timeoutMs: 30_000,
+  maxRetries: 2,
+});
+
+const code = await unblocked.context.search.code({
+  query: "rate limiting",
+});
+
+const research = await unblocked.context.research({
+  query: "How does auth work?",
+});
+```
+
+## Considered Alternatives
+
+The design pass considered a single `invoke("tool_name", input)` interface, a
+pure OpenAPI-generated REST client, and framework-specific adapters for Flue or
+Eve. The selected surface keeps the common path readable, avoids coupling to a
+framework that may change quickly, and still leaves an escape hatch for advanced
+callers.

package/docs/authentication.md

@@ -0,0 +1,71 @@
+# Authentication
+
+The SDK uses the same authentication model as the Unblocked Public API. Each request includes:
+
+```http
+Authorization: Bearer <token>
+```
+
+## Token Types
+
+Unblocked supports two API token styles:
+
+- Personal Access Tokens for user-scoped automation, testing, and development workflows.
+- Team Access Tokens for organization-wide automation.
+
+Use the narrowest token that can perform the job. For agent workflows, prefer data-source-scoped tokens when possible.
+
+## Passing a Token
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+
+const unblocked = new Unblocked({
+  apiKey: "unb_...",
+});
+```
+
+`token` is an alias for `apiKey`:
+
+```ts
+const unblocked = new Unblocked({
+  token: "unb_...",
+});
+```
+
+## Environment Variables
+
+If no token is passed, the client reads environment variables in this order:
+
+1. `UNBLOCKED_API_TOKEN`
+2. `UNBLOCKED_API_KEY`
+
+```bash
+export UNBLOCKED_API_TOKEN="unb_..."
+```
+
+```ts
+const unblocked = new Unblocked();
+```
+
+## Async Token Providers
+
+Use a token provider when the token comes from a secrets manager or short-lived credential service.
+
+```ts
+const unblocked = new Unblocked({
+  apiKey: async () => {
+    return await getTokenFromSecretManager();
+  },
+});
+```
+
+The provider is called before each request, so it can refresh or rotate credentials.
+
+## Security Notes
+
+- Do not commit tokens to source control.
+- Do not expose team tokens in browser code.
+- Prefer server-side or agent-runtime usage for SDK calls.
+- Rotate tokens when they are no longer needed.
+- Scope tokens to the minimum data sources required by the workflow.

package/docs/configuration.md

@@ -0,0 +1,67 @@
+# Configuration
+
+Create a client with `UnblockedClientOptions`.
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+  baseUrl: "https://getunblocked.com/api",
+  timeoutMs: 30_000,
+  maxRetries: 2,
+  retryDelayMs: 500,
+  headers: {
+    "User-Agent": "my-agent/1.0",
+  },
+  fetch: globalThis.fetch,
+});
+```
+
+## Options
+
+`apiKey`:
+API token string or async token provider. If omitted, the SDK reads `UNBLOCKED_API_TOKEN` and then `UNBLOCKED_API_KEY`.
+
+`token`:
+Alias for `apiKey`.
+
+`baseUrl`:
+Base URL for the public API. Defaults to `https://getunblocked.com/api`.
+
+`fetch`:
+Fetch implementation. Defaults to `globalThis.fetch`.
+
+`headers`:
+Headers included on every request. The SDK still controls `Authorization`, `Accept`, and `Content-Type` for JSON requests. The SDK also sets a default `User-Agent` (e.g. `@getunblocked/sdk/0.1.0 node/20.x`) that you can override here. Browsers ignore custom `User-Agent` values.
+
+`timeoutMs`:
+Maximum time for each HTTP request before the request is aborted. Defaults to `60000` (60 seconds).
+
+`maxRetries`:
+Maximum number of retry attempts for retriable requests. Defaults to `2`.
+
+`retryDelayMs`:
+Base delay used for exponential backoff. Defaults to `500`.
+
+`dangerouslyAllowBrowser`:
+By default the client throws if constructed in a browser-like environment, to keep your API token out of client-side bundles. Set to `true` only if you understand the risk (e.g. you proxy the API or use a restricted token).
+
+## Per-Request Options
+
+Most methods accept request options as the final argument.
+
+```ts
+await unblocked.context.research(
+  {
+    query: "How does auth work?",
+  },
+  {
+    timeoutMs: 10_000,
+    maxRetries: 1,
+    signal: abortController.signal,
+  },
+);
+```
+
+Per-request options override client-level options for that call.

package/docs/context.md

@@ -0,0 +1,131 @@
+# Context
+
+The `client.context` resource is the SDK's interface to Unblocked's context engine. Every context method sends a `POST` to a `/tools/context/*` endpoint (under the `https://getunblocked.com/api` base URL) and resolves to a response carrying `sources`.
+
+## Response Shape
+
+Search, query, and get methods return a response with a `sources` array. `research` additionally returns a `summary` and the `effort` that was used.
+
+```ts
+interface ContextSearchSource {
+  content: string;
+  title?: string;
+  url?: string;
+  sourceType?: "code" | "pull_request" | "issue" | "messages" | "documentation" | "rules";
+  provider?: string;
+}
+
+interface ContextSearchResponse {
+  toolCallId?: string;
+  sources: ContextSearchSource[];
+}
+
+interface ContextResearchResponse {
+  toolCallId?: string;
+  summary: string;
+  sources: ContextSearchSource[];
+  effort: "low" | "medium" | "high";
+}
+```
+
+`ContextQueryResponse` and `ContextGetResponse` have the same shape as `ContextSearchResponse` (`{ toolCallId?, sources }`).
+
+```ts
+const result = await unblocked.context.research({
+  query: "How does the user authentication system work?",
+});
+
+console.log(result.summary);
+for (const source of result.sources) {
+  console.log(source.content);
+  if (source.url) {
+    console.log(source.url);
+  }
+}
+```
+
+## Common Request Fields
+
+Every request accepts optional `toolCallId` and `sessionId` strings that correlate a call with its originating tool call and group related context calls. They are always optional.
+
+## Effort Levels
+
+Only `research` accepts an optional `effort` that trades breadth for latency:
+
+- `low` - quick lookup, fastest and narrowest.
+- `medium` - normal, balanced depth (the server default when `effort` is omitted).
+- `high` - broad cross-system research, slowest and most thorough.
+
+```ts
+import type { ContextSearchEffort } from "@getunblocked/sdk";
+
+const effort: ContextSearchEffort = "high";
+```
+
+## Research
+
+`client.context.research(request, options?)` runs unified multi-source research and synthesizes an answer with references.
+
+```ts
+await unblocked.context.research({
+  query: "How does the user authentication system work?",
+  instruction: "Focus on token refresh.",
+  effort: "high",
+});
+```
+
+Request fields: `query` (required), `instruction` (optional), `effort` (optional), plus optional `toolCallId` and `sessionId`. Returns `ContextResearchResponse` (`summary`, `sources`, `effort`).
+
+## Search
+
+`client.context.search.*` searches a single source. Each method takes `{ query, instruction? }` (plus optional `toolCallId`/`sessionId`) and returns `ContextSearchResponse`.
+
+```ts
+await unblocked.context.search.code({ query: "rate limiting" });
+await unblocked.context.search.prs({ query: "auth refactor" });
+await unblocked.context.search.issues({ query: "logout after workspace switch" });
+await unblocked.context.search.documentation({ query: "session lifecycle" });
+await unblocked.context.search.messages({ query: "incident 2024-05" });
+```
+
+| Method | Endpoint |
+| --- | --- |
+| `search.code` | `/tools/context/search/code` |
+| `search.prs` | `/tools/context/search/prs` |
+| `search.documentation` | `/tools/context/search/documentation` |
+| `search.issues` | `/tools/context/search/issues` |
+| `search.messages` | `/tools/context/search/messages` |
+
+## Query
+
+`client.context.query.*` queries issues or pull requests, optionally scoped by `projects` and/or `user_name`. Each method takes `{ query, projects?, user_name? }` (plus optional `toolCallId`/`sessionId`) and returns `ContextQueryResponse`.
+
+```ts
+await unblocked.context.query.issues({ query: "open bugs", projects: ["web"], user_name: "alice" });
+await unblocked.context.query.prs({ query: "recent auth changes", projects: ["api"] });
+```
+
+## Get
+
+`client.context.get.*` fetches specific resources.
+
+```ts
+await unblocked.context.get.urls({ urls: ["https://example.com/docs"] });
+await unblocked.context.get.rules({ repoName: "acme/web", task: "add endpoint", language: "typescript", paths: ["src/auth"] });
+```
+
+- `get.urls` takes `{ urls }` (required) plus optional `toolCallId`/`sessionId`, and summarizes the content of specific URLs. Returns `ContextGetResponse`.
+- `get.rules` takes `{ repoName }` (required) plus optional `ruleId`, `task`, `language`, `paths`, `toolCallId`, and `sessionId`, and returns the coding rules and conventions for a repository. Returns `ContextGetResponse`.
+
+## Request Options
+
+Every method accepts an optional second `RequestOptions` argument for per-call `headers`, `signal`, `timeoutMs`, `maxRetries`, and `retryDelayMs`; because context methods use `POST`, retry options are accepted but do not trigger retries.
+
+```ts
+await unblocked.context.research(
+  { query: "How does auth work?" },
+  { timeoutMs: 90_000 },
+);
+```
+
+Context methods use `POST` and are never retried. See [Errors and Retries](./errors-and-retries.md).

package/docs/contributing.md

@@ -0,0 +1,51 @@
+# Contributing
+
+## Setup
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Test
+
+```bash
+npm test
+```
+
+The test command builds the package and runs Node's built-in test runner against the emitted `dist` files.
+
+## Package Dry Run
+
+```bash
+npm pack --dry-run
+```
+
+If your local npm cache has permission issues, use a temporary cache:
+
+```bash
+npm --cache /private/tmp/unblocked-typescript-sdk-npm-cache pack --dry-run
+```
+
+## Development Guidelines
+
+- Keep runtime dependencies at zero unless there is a strong reason to add one.
+- Prefer resource methods for stable public API endpoints.
+- Use `request` and `requestRaw` as escape hatches, not as the primary documented path.
+- Add or update tests for request construction, auth headers, retries, errors, and type exports.
+- Keep docs in `docs/` updated when changing public behavior.
+- Do not commit generated package tarballs.
+
+## Source Layout
+
+- `src/client.ts` - public resource clients.
+- `src/http.ts` - fetch transport, retries, timeouts, and pagination parsing.
+- `src/types.ts` - exported public types.
+- `src/errors.ts` - exported error classes.
+- `src/agents.ts` - framework-neutral agent tool helpers.
+- `tests/` - tests against built `dist` output.

package/docs/errors-and-retries.md

@@ -0,0 +1,135 @@
+# Errors and Retries
+
+## API Errors
+
+Non-2xx responses throw `UnblockedApiError`.
+
+```ts
+import { UnblockedApiError } from "@getunblocked/sdk";
+
+try {
+  await unblocked.context.research({ query: "How does auth work?" });
+} catch (error) {
+  if (error instanceof UnblockedApiError) {
+    console.error(error.status);
+    console.error(error.statusText);
+    console.error(error.body);
+    console.error(error.requestId); // X-Request-ID, useful for support
+  }
+}
+```
+
+`UnblockedApiError` includes:
+
+- `status`
+- `statusText`
+- `url`
+- `method`
+- `body` — the parsed `ApiError` body (`status`, optional `title`, `detail`, `url`, `urlLabel`, `cause`)
+- `headers`
+- `requestId` — the `X-Request-ID` response header, when present
+
+The error `message` includes the `title`/`detail` from the response body when the API provides them.
+
+## Error Subclasses
+
+The thrown error is a status-specific subclass of `UnblockedApiError`, so you can match on the case you care about:
+
+| Status | Class |
+| --- | --- |
+| 400 | `UnblockedBadRequestError` |
+| 401 | `UnblockedAuthenticationError` |
+| 403 | `UnblockedPermissionDeniedError` |
+| 404 | `UnblockedNotFoundError` |
+| 429 | `UnblockedRateLimitError` |
+| 5xx | `UnblockedServerError` |
+
+Any other non-2xx status throws the base `UnblockedApiError`.
+
+```ts
+import { UnblockedRateLimitError } from "@getunblocked/sdk";
+
+try {
+  await unblocked.context.research({ query: "How does auth work?" });
+} catch (error) {
+  if (error instanceof UnblockedRateLimitError) {
+    // Rate limit exceeded — back off and retry later.
+  }
+}
+```
+
+## Timeouts
+
+HTTP request timeouts throw `UnblockedTimeoutError`.
+
+```ts
+import { UnblockedTimeoutError } from "@getunblocked/sdk";
+
+try {
+  await unblocked.context.research(
+    { query: "How does auth work?" },
+    { timeoutMs: 30_000 },
+  );
+} catch (error) {
+  if (error instanceof UnblockedTimeoutError) {
+    console.error(error.message);
+  }
+}
+```
+
+## Retry Behavior
+
+The SDK retries transient network failures and these response statuses:
+
+- `408`
+- `429`
+- `500`
+- `502`
+- `503`
+- `504`
+
+Only `GET`, `PUT`, and `DELETE` are retried by default. `POST` and `PATCH` are never retried because they are not generally safe to replay. All `client.context.*` methods use `POST`, so `maxRetries` has no effect on context calls.
+
+The default retry settings are:
+
+```ts
+{
+  maxRetries: 2,
+  retryDelayMs: 500,
+}
+```
+
+`Retry-After` response headers are respected when present.
+
+## Override Retries
+
+```ts
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+  maxRetries: 0,
+});
+```
+
+Per request:
+
+```ts
+await unblocked.request("GET", "/some/idempotent/path", {
+  maxRetries: 1,
+  retryDelayMs: 250,
+});
+```
+
+Context methods use `POST` and are never retried. Passing `maxRetries` to `client.context.*` only records an option the retry loop will not use; retry options affect idempotent low-level `GET`, `PUT`, and `DELETE` requests through `request`/`requestRaw`.
+
+## Abort Signals
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5_000);
+
+await unblocked.context.research(
+  { query: "How does auth work?" },
+  { signal: controller.signal },
+);
+```