@getunblocked/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Next Chapter Software, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# Unblocked TypeScript SDK
+
+Lightweight TypeScript wrapper for the [Unblocked Public API](https://docs.getunblocked.com/api-reference/quickstart).
+
+The SDK uses the same API token authentication as the public API: pass a Personal Access Token or Team Access Token as a bearer token. You can pass the token explicitly or set `UNBLOCKED_API_TOKEN`.
+
+## Install
+
+```bash
+bun add @getunblocked/sdk
+# or: npm install @getunblocked/sdk
+```
+
+The package is a public scoped package on npm. The compiled `dist/` is committed
+to the repo too, so a direct git install needs no build step and pulls in no
+dependencies (the SDK has zero runtime dependencies):
+
+```bash
+bun add git+ssh://git@github.com/unblocked/unblocked-typescript-sdk.git#v0.1.0
+```
+
+Always pin a tag (e.g. `#v0.1.0`) for git installs so they're reproducible —
+omitting it tracks the default branch.
+
+> The `github:owner/repo` shorthand and plain `https` git URLs go through GitHub's unauthenticated tarball API, which 404s on a private repo. Use the `git+ssh://` URL above (or a tokenized `https` URL) so a git install authenticates.
+
+> **Public template extraction:** now that the SDK package is public, `examples/eve-pr-triage` can be extracted into its own repo (`unblocked/eve-pr-triage-agent`, configured as a GitHub *template* repo for the "Use this template" button — no `-template` suffix; keep `eve` in the name for harness discoverability). Swap its `@getunblocked/sdk` dependency from `file:../..` to the published package and drop the `predeploy`/`postdeploy` tarball step. Leave a link-out here and in `docs/agent-frameworks.md`. The extraction's benefits (Vercel deploy button, public showcase, own issue tracker) switch on once the SDK is public.
+
+> **When the GitHub repo goes public:** enable npm provenance — add `id-token: write` to the `permissions` block in `publish.yml` and `--provenance` to the `npm publish` step. Provenance is blocked while the *source repo* is private (the attestation publishes repo/workflow metadata to the public Sigstore log), even though the npm package itself is public.
+
+## Quickstart
+
+```ts
+import Unblocked from "@getunblocked/sdk";
+
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+});
+
+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);
+}
+
+const code = await unblocked.context.search.code({
+  query: "rate limiting",
+});
+
+const urls = await unblocked.context.get.urls({
+  urls: ["https://my.company.com/apollo/ticket/123456"],
+});
+```
+
+The same flow is available as a runnable script — from a clone of this repo (no install or build step needed):
+
+```bash
+UNBLOCKED_API_TOKEN=unb_... node examples/quickstart.mjs "How does auth work?"
+```
+
+## Documentation
+
+Detailed guides live in [`docs/`](./docs/README.md):
+
+- [Getting Started](./docs/getting-started.md)
+- [Authentication](./docs/authentication.md)
+- [Configuration](./docs/configuration.md)
+- [Context](./docs/context.md)
+- [Pagination](./docs/pagination.md)
+- [Errors and Retries](./docs/errors-and-retries.md)
+- [Agent Frameworks](./docs/agent-frameworks.md)
+- [Low-Level Requests](./docs/low-level-requests.md)
+- [Runtime and Packaging](./docs/runtime-and-packaging.md)
+- [TypeScript Guide](./docs/typescript.md)
+
+## Authentication
+
+Unblocked supports Personal Access Tokens and Team Access Tokens. Both are sent as:
+
+```http
+Authorization: Bearer <token>
+```
+
+The client resolves tokens in this order:
+
+1. `new Unblocked({ apiKey })`
+2. `new Unblocked({ token })`
+3. `UNBLOCKED_API_TOKEN`
+4. `UNBLOCKED_API_KEY`
+
+`apiKey` and `token` can also be async token providers:
+
+```ts
+const unblocked = new Unblocked({
+  apiKey: async () => getTokenFromSecretManager(),
+});
+```
+
+## Client Options
+
+```ts
+const unblocked = new Unblocked({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+  baseUrl: "https://getunblocked.com/api",
+  timeoutMs: 30_000,
+  maxRetries: 2,
+  retryDelayMs: 500,
+  fetch: globalThis.fetch,
+});
+```
+
+`GET`, `PUT`, and `DELETE` requests retry transient network failures and `408`, `429`, `500`, `502`, `503`, and `504` responses. `POST` and `PATCH` are not retried by default because they are not generally safe to replay.
+
+## API Surface
+
+```ts
+const unblocked = new Unblocked();
+
+await unblocked.context.research({ query, instruction, effort });
+
+await unblocked.context.search.code({ query, instruction });
+await unblocked.context.search.prs({ query, instruction });
+await unblocked.context.search.issues({ query, instruction });
+await unblocked.context.search.documentation({ query, instruction });
+await unblocked.context.search.messages({ query, instruction });
+
+await unblocked.context.query.issues({ query, projects, user_name });
+await unblocked.context.query.prs({ query, projects, user_name });
+
+await unblocked.context.get.urls({ urls });
+await unblocked.context.get.rules({ repoName, ruleId, task, language, paths });
+```
+
+Search, query, and get methods resolve to `{ sources: ContextSearchSource[] }`. Research also returns a `summary` and the `effort` used:
+
+```ts
+const research = await unblocked.context.research({ query: "How does auth work?" });
+
+research.summary;   // string
+research.sources;   // [{ content, title?, url?, sourceType?, provider? }, ...]
+research.effort;    // "low" | "medium" | "high"
+
+const code = await unblocked.context.search.code({ query: "rate limiting" });
+code.sources;       // [{ content, title?, url?, sourceType?, provider? }, ...]
+```
+
+See [`docs/context.md`](./docs/context.md) for the full surface and effort levels.
+
+## Low-Level Requests
+
+The resource methods cover the public API, but the client also exposes typed request helpers for new endpoints or advanced callers:
+
+```ts
+const result = await unblocked.request("POST", "/tools/context/research", {
+  body: { query: "How does auth work?" },
+});
+```
+
+## Agent Frameworks
+
+The SDK exports plain functions and JSON-schema-shaped descriptors so frameworks can adapt them without pulling in framework-specific dependencies.
+
+```ts
+import { createUnblockedTools, unblockedToolSchemas } from "@getunblocked/sdk";
+
+const tools = createUnblockedTools({
+  apiKey: process.env.UNBLOCKED_API_TOKEN,
+});
+
+export const research = {
+  ...unblockedToolSchemas.research,
+  execute: tools.research,
+};
+```
+
+For frameworks such as Flue or Eve, put the wrapper above in the framework's TypeScript tool file and let that framework handle its own tool registration conventions.
+
+See [`examples/quickstart.mjs`](./examples/quickstart.mjs) for a minimal runnable script, and `examples/context-research-tool.ts` for the tool-module pattern above.
+
+For a full local programmable-harness demo, see [`examples/flue-bug-triage`](./examples/flue-bug-triage/README.md). For a deployable GitHub-App-webhook PR-triage agent that makes Unblocked context a required triage step, see [`examples/eve-pr-triage`](./examples/eve-pr-triage/README.md).
+
+## Runtime Support
+
+- ESM package
+- No runtime dependencies
+- Uses the platform `fetch`
+- Requires Node.js 18+ or any runtime with `fetch`
+
+## Error Handling
+
+Non-2xx API responses throw `UnblockedApiError` with `status`, `statusText`, response `headers`, parsed response `body`, and `requestId` (the `X-Request-ID` header). The thrown error is a status-specific subclass — `UnblockedBadRequestError` (400), `UnblockedAuthenticationError` (401), `UnblockedPermissionDeniedError` (403), `UnblockedNotFoundError` (404), `UnblockedRateLimitError` (429), and `UnblockedServerError` (5xx) — all extending `UnblockedApiError`. Request timeouts throw `UnblockedTimeoutError`.
+
+```ts
+import { UnblockedApiError, UnblockedTimeoutError } from "@getunblocked/sdk";
+
+try {
+  await unblocked.context.research({ query: "How does auth work?" });
+} catch (error) {
+  if (error instanceof UnblockedApiError) {
+    console.error(error.status, error.body, error.requestId);
+  } else if (error instanceof UnblockedTimeoutError) {
+    console.error(error.message);
+  }
+}
+```
+
+See [`docs/errors-and-retries.md`](./docs/errors-and-retries.md) for the full subclass table.

package/dist/agents.d.ts

@@ -0,0 +1,301 @@
+import { UnblockedClient } from "./client.js";
+import type { ContextGetResponse, ContextGetRulesRequest, ContextGetUrlsRequest, ContextQueryIssuesRequest, ContextQueryPrsRequest, ContextQueryResponse, ContextResearchRequest, ContextResearchResponse, ContextSearchRequest, ContextSearchResponse, UnblockedClientOptions } from "./types.js";
+export interface UnblockedAgentTools {
+    research(input: ContextResearchRequest): Promise<ContextResearchResponse>;
+    searchCode(input: ContextSearchRequest): Promise<ContextSearchResponse>;
+    searchPrs(input: ContextSearchRequest): Promise<ContextSearchResponse>;
+    searchIssues(input: ContextSearchRequest): Promise<ContextSearchResponse>;
+    searchDocumentation(input: ContextSearchRequest): Promise<ContextSearchResponse>;
+    searchMessages(input: ContextSearchRequest): Promise<ContextSearchResponse>;
+    queryIssues(input: ContextQueryIssuesRequest): Promise<ContextQueryResponse>;
+    queryPrs(input: ContextQueryPrsRequest): Promise<ContextQueryResponse>;
+    getUrls(input: ContextGetUrlsRequest): Promise<ContextGetResponse>;
+    getRules(input: ContextGetRulesRequest): Promise<ContextGetResponse>;
+}
+export declare function createUnblockedTools(clientOrOptions?: UnblockedClient | UnblockedClientOptions): UnblockedAgentTools;
+export declare const unblockedToolSchemas: {
+    readonly research: {
+        readonly description: "Unified multi-source research across all connected context; synthesizes an answer with references.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The research question to investigate.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the research is performed or presented.";
+                };
+                readonly effort: {
+                    readonly type: "string";
+                    readonly enum: readonly ["low", "medium", "high"];
+                    readonly description: "Effort level: low (quick lookup), medium (normal), high (broad cross-system research).";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly searchCode: {
+        readonly description: "Search the connected codebase for relevant code.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The code search query.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the search is performed or presented.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly searchPrs: {
+        readonly description: "Search pull requests for relevant changes and discussion.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The pull request search query.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the search is performed or presented.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly searchIssues: {
+        readonly description: "Search issues for relevant reports and discussion.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The issue search query.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the search is performed or presented.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly searchDocumentation: {
+        readonly description: "Search connected documentation for relevant content.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The documentation search query.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the search is performed or presented.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly searchMessages: {
+        readonly description: "Search connected messages and conversations for relevant discussion.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The message search query.";
+                };
+                readonly instruction: {
+                    readonly type: "string";
+                    readonly description: "Optional guidance shaping how the search is performed or presented.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly queryIssues: {
+        readonly description: "Query issues by natural-language query, optionally scoped by projects and/or user.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The issue query.";
+                };
+                readonly projects: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Optional list of projects to scope the query to.";
+                };
+                readonly user_name: {
+                    readonly type: "string";
+                    readonly description: "Optional user name to scope the query to.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly queryPrs: {
+        readonly description: "Query pull requests by natural-language query, optionally scoped by projects and/or user.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly query: {
+                    readonly type: "string";
+                    readonly description: "The pull request query.";
+                };
+                readonly projects: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Optional list of projects to scope the query to.";
+                };
+                readonly user_name: {
+                    readonly type: "string";
+                    readonly description: "Optional user name to scope the query to.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["query"];
+        };
+    };
+    readonly getUrls: {
+        readonly description: "Fetch and summarize the content of specific URLs.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly urls: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "The URLs to fetch content for.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["urls"];
+        };
+    };
+    readonly getRules: {
+        readonly description: "Get the coding rules and conventions for a repository, optionally scoped by task, language, and paths.";
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly repoName: {
+                    readonly type: "string";
+                    readonly description: "The repository to fetch rules for.";
+                };
+                readonly ruleId: {
+                    readonly type: "string";
+                    readonly description: "Optional specific rule identifier to fetch.";
+                };
+                readonly task: {
+                    readonly type: "string";
+                    readonly description: "Optional task description to scope the rules lookup to.";
+                };
+                readonly language: {
+                    readonly type: "string";
+                    readonly description: "Optional programming language to scope the rules lookup to.";
+                };
+                readonly paths: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Optional file paths to scope the rules lookup to.";
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly description: "Optional identifier correlating this call with the originating tool call.";
+                };
+                readonly sessionId: {
+                    readonly type: "string";
+                    readonly description: "Optional session identifier grouping related context calls.";
+                };
+            };
+            readonly required: readonly ["repoName"];
+        };
+    };
+};
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1E,UAAU,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxE,SAAS,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACvE,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1E,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjF,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5E,WAAW,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACnE,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACtE;AAED,wBAAgB,oBAAoB,CAAC,eAAe,GAAE,eAAe,GAAG,sBAA2B,GAAG,mBAAmB,CAmCxH;AAYD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwNvB,CAAC"}