@wireweave/sdk 0.1.1-beta.9 → 0.2.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,92 +1,29 @@
1
1
  # @wireweave/sdk
2
2
 
3
- The platform client for Wireweave — a typed HTTP client, token-based auth, and an in-process local tool runner, all behind a single `dispatch()` entry point.
3
+ The typed dispatch and I/O adapter used by Wireweave clients.
4
4
 
5
- ## What it does
5
+ The [public tool contract](https://github.com/wireweave/wireweave/blob/develop/docs/spec/TOOLING.md#3-sdk-dispatch-and-io-admission) defines this package's APIs, behavior, configuration and compatibility. The [language contract](https://github.com/wireweave/wireweave/blob/develop/docs/spec/LANGUAGE.md) defines the DSL. Package metadata owns versions, exports, dependencies and scripts.
6
6
 
7
- `@wireweave/sdk` is the contract owner shared by the Wireweave CLI, MCP server, and skill packages. It exposes one tool-dispatch surface that routes each call to the right place:
7
+ ## Installation
8
8
 
9
- - **Local tools** run in-process via `@wireweave/core`, `@wireweave/ux-rules`, and `@wireweave/language-data`. No network call, no API key required.
10
- - **Remote tools** are proxied to the Wireweave API server (`api-server`) over HTTP. These require an API key (cloud project/wireframe storage, account & billing, hosted reference content such as the grammar and LLM guide).
11
-
12
- The list of local tools and the endpoint map for remote tools are generated from the api-server contract (`src/generated/`), so consumers never hand-maintain routing.
13
-
14
- Local dispatch tools:
15
-
16
- `wireweave_parse` · `wireweave_validate` · `wireweave_render_html_code` · `wireweave_validate_ux` · `wireweave_diff` · `wireweave_analyze` · `wireweave_list_components` · `wireweave_export_json` · `wireweave_export_figma`
17
-
18
- ## Install
9
+ Use Node.js >=22.13.0. Replace `<pinned-version>` with the release selected for your toolchain.
19
10
 
20
11
  ```bash
21
- npm install @wireweave/sdk
22
- ```
23
-
24
- Requires Node.js 20+.
25
-
26
- ## Usage
27
-
28
- ```ts
29
- import { dispatch, toolEndpoints, type ApiConfig } from '@wireweave/sdk'
30
-
31
- const apiConfig: ApiConfig = {
32
- apiUrl: 'https://api.wireweave.org',
33
- apiKey: process.env.WIREWEAVE_API_KEY ?? '', // empty is fine for local tools
34
- }
35
-
36
- // Local tool — runs in-process, no network, no key needed.
37
- const parsed = await dispatch(
38
- 'wireweave_parse',
39
- { source: 'Page "Home"' },
40
- { apiConfig, endpoints: toolEndpoints },
41
- )
42
-
43
- // Remote tool — proxied to api-server, requires a valid apiKey.
44
- const saved = await dispatch(
45
- 'wireweave_cloud_save_wireframe',
46
- { name: 'Home', source },
47
- { apiConfig, endpoints: toolEndpoints },
48
- )
49
- ```
50
-
51
- Run a local tool directly, bypassing dispatch:
52
-
53
- ```ts
54
- import { localDispatch, isLocalDispatchTool } from '@wireweave/sdk'
55
-
56
- if (isLocalDispatchTool('wireweave_diff')) {
57
- const result = localDispatch('wireweave_diff', { oldSource, newSource })
58
- }
12
+ pnpm add --save-exact '@wireweave/sdk@<pinned-version>'
59
13
  ```
60
14
 
61
- Authentication helpers persist a token at `~/.wireweave/config.json` (`0600`):
15
+ `dispatch` validates arguments against the shared public tool schema before execution. Local tools never require an account or perform a remote fallback. Remote calls send the supplied API key to the configured API URL, reject redirects and have a 30-second timeout. Pass `DispatchOptions.signal` to cancel pending work. See the [MCP adapter's credential and data-flow guide](https://github.com/wireweave/wireweave/tree/main/packages/mcp-server#http-and-credentials) and [Privacy Policy](https://www.wireweave.org/privacy) for hosted-service behavior.
62
16
 
63
- ```ts
64
- import { saveToken, loadToken, verifyToken, clearToken } from '@wireweave/sdk'
17
+ ## Development
65
18
 
66
- const check = await verifyToken(token, 'https://api.wireweave.org', '/verify')
67
- if (check.valid) await saveToken({ token })
19
+ Run from the monorepo root after the [workspace setup](https://github.com/wireweave/wireweave#workspace-commands).
68
20
 
69
- const stored = await loadToken() // { token, apiUrl? } | null
70
- await clearToken()
21
+ ```bash
22
+ pnpm --filter @wireweave/sdk run build
23
+ pnpm --filter @wireweave/sdk run typecheck
24
+ pnpm --filter @wireweave/sdk run lint
25
+ pnpm --filter @wireweave/sdk run test
26
+ pnpm --filter @wireweave/sdk run format:check
71
27
  ```
72
28
 
73
- ## API
74
-
75
- | Export | Description |
76
- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
- | `dispatch(name, args, options)` | Single entry point. Routes local tools to `localDispatch`, remote tools to `callApi`. |
78
- | `localDispatch(name, args)` | Runs a local tool in-process (parse, validate, render, diff, analyze, export, etc.). |
79
- | `isLocalDispatchTool(name)` | `true` if the tool is dispatched locally. |
80
- | `LOCAL_DISPATCH_TOOL_NAMES` | `ReadonlySet<string>` of local tool names. |
81
- | `callApi(config, endpoint, args, fetchFn?)` | Low-level HTTP call to an api-server endpoint. |
82
- | `buildRequest(config, endpoint, args?)` | Builds the URL and `RequestInit` for an endpoint (path params, query, body). |
83
- | `extractCreditInfo(headers)` / `parseErrorMessage(status, body)` | Credit-header parsing and HTTP-status-to-message mapping. |
84
- | `loadToken` / `saveToken` / `clearToken` / `verifyToken` / `getConfigPath` | Token persistence and verification. |
85
- | `tools` / `toolEndpoints` | Generated tool definitions and the remote endpoint map (api-server contract). |
86
- | Types | `ApiConfig`, `ApiResult`, `ApiErrorBody`, `HttpMethod`, `ToolEndpoint`, `CreditInfo`, `LocalToolResult`, `LocalToolContentBlock`, `DispatchOptions`, `AuthOptions`, `StoredConfig`, `VerifyTokenResult` |
87
-
88
- Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
89
-
90
- ## License
91
-
92
- MIT
29
+ License: MIT.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { Tool } from '@modelcontextprotocol/sdk/types.js';
1
+ import { Tool, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
2
2
 
3
3
  interface ApiConfig {
4
4
  apiUrl: string;
@@ -9,9 +9,9 @@ interface CreditInfo {
9
9
  monthlyRemaining?: number;
10
10
  totalAvailable?: number;
11
11
  }
12
- type HttpMethod$1 = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
13
- interface ToolEndpoint$1 {
14
- method: HttpMethod$1;
12
+ type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
13
+ interface ToolEndpoint {
14
+ method: HttpMethod;
15
15
  path: string;
16
16
  pathParams?: string[];
17
17
  }
@@ -33,14 +33,14 @@ interface LocalToolResult {
33
33
  [key: string]: unknown;
34
34
  }
35
35
 
36
- declare function buildRequest(config: ApiConfig, endpoint: ToolEndpoint$1, args?: Record<string, unknown>): {
36
+ declare function buildRequest(config: ApiConfig, endpoint: ToolEndpoint, args?: Record<string, unknown>): {
37
37
  url: string;
38
38
  options: RequestInit;
39
39
  bodyForGet: Record<string, unknown>;
40
40
  };
41
41
  declare function parseErrorMessage(status: number, error: ApiErrorBody): string;
42
42
  declare function extractCreditInfo(headers: Headers): CreditInfo;
43
- declare function callApi(config: ApiConfig, endpoint: ToolEndpoint$1, args?: Record<string, unknown>, fetchFn?: typeof fetch): Promise<unknown>;
43
+ declare function callApi(config: ApiConfig, endpoint: ToolEndpoint, args?: Record<string, unknown>, fetchFn?: typeof fetch, signal?: AbortSignal): Promise<unknown>;
44
44
 
45
45
  interface StoredConfig {
46
46
  token: string;
@@ -67,31 +67,25 @@ declare function localDispatch(toolName: string, args: Record<string, unknown>):
67
67
 
68
68
  interface DispatchOptions {
69
69
  apiConfig: ApiConfig;
70
- endpoints: Record<string, ToolEndpoint$1>;
70
+ endpoints: Record<string, ToolEndpoint>;
71
71
  fetchFn?: typeof fetch;
72
+ signal?: AbortSignal;
72
73
  }
73
74
  declare function dispatch(toolName: string, args: Record<string, unknown>, options: DispatchOptions): Promise<LocalToolResult>;
74
75
 
75
76
  /**
76
- * MCP Tool Definitions
77
- *
78
- * ⚠️ AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
79
- *
80
- * This file is generated by the Wireweave team.
81
- * To request changes, please open an issue at:
82
- * https://github.com/wireweave/mcp-server/issues
83
- *
84
- * Generated: 2026-05-17T13:36:37.806Z
85
- * Public tools: 32 (local: 9, server: 23)
77
+ * AUTO-GENERATED. Do not edit directly.
78
+ * Source: packages/sdk/src/tool-catalog.json
79
+ * Regenerate: node scripts/generate-tool-catalog.mjs --write
80
+ * Verify: node scripts/generate-tool-catalog.mjs --check
86
81
  */
87
82
 
88
- declare const tools: Tool[];
89
- type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
90
- interface ToolEndpoint {
91
- method: HttpMethod;
92
- path: string;
93
- pathParams?: string[];
94
- }
83
+ type RequiredToolAnnotations = Required<Pick<ToolAnnotations, 'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>>;
84
+ type AnnotatedTool = Tool & {
85
+ annotations: RequiredToolAnnotations;
86
+ };
87
+ declare const tools: AnnotatedTool[];
95
88
  declare const toolEndpoints: Record<string, ToolEndpoint>;
89
+ declare const localToolNames: ReadonlySet<string>;
96
90
 
97
- export { type ApiConfig, type ApiErrorBody, type ApiResult, type AuthOptions, type CreditInfo, type DispatchOptions, type HttpMethod$1 as HttpMethod, LOCAL_DISPATCH_TOOL_NAMES, type LocalToolContentBlock, type LocalToolResult, type StoredConfig, type ToolEndpoint$1 as ToolEndpoint, type VerifyTokenResult, buildRequest, callApi, clearToken, dispatch, extractCreditInfo, getConfigPath, isLocalDispatchTool, loadToken, localDispatch, parseErrorMessage, saveToken, toolEndpoints, tools, verifyToken };
91
+ export { type AnnotatedTool, type ApiConfig, type ApiErrorBody, type ApiResult, type AuthOptions, type CreditInfo, type DispatchOptions, type HttpMethod, LOCAL_DISPATCH_TOOL_NAMES, type LocalToolContentBlock, type LocalToolResult, type RequiredToolAnnotations, type StoredConfig, type ToolEndpoint, type VerifyTokenResult, buildRequest, callApi, clearToken, dispatch, extractCreditInfo, getConfigPath, isLocalDispatchTool, loadToken, localDispatch, localToolNames, parseErrorMessage, saveToken, toolEndpoints, tools, verifyToken };