@typeship-ax/mcp 0.6.0

package/api.md

@@ -0,0 +1,512 @@
+# typeship — API reference
+
+Version 0.6.0. Generated by typeship; regenerate rather than editing.
+
+All methods return `ApiResult<T, E>`: check `result.ok`, or `unwrap(result)` to throw typed errors.
+
+For complete input and output schemas, use [`api.json`](./api.json), the machine-readable companion to this reference. Collapsed wire arguments below use API field names for CLI and MCP; SDK calls use the native signature shown in each heading.
+
+## generate
+
+### `client.generate.run(body)`
+
+Generate a package from a spec
+
+`POST /generate`
+
+Stateless generation: nothing is stored. Returns the full generated
+package as files. Works without an API key: anonymous calls generate
+the first 25 operations, rate limited per IP address, and the
+response's `limits` object says what was held back and where to lift
+it; anonymous calls from a spec URL also carry `claim.url`, a link
+that turns the run into a project once a person signs in. With a key, the free plan generates the first 25 operations and
+paid plans generate the whole spec. A present but invalid key is a
+401, not a downgrade to anonymous.
+
+Safety: **write** · Authentication: **optional**
+
+Body: `GenerateRequest` (required)
+
+Returns: `GenerationResult`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `PayloadTooLargeError` (413), `UnprocessableEntityError` (422), `RateLimitedError` (429), `ApiResponseError` (default)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec": {
+    "url": "https://example.com"
+  },
+  "outputs": [
+    "typescript-sdk"
+  ]
+}
+```
+
+</details>
+
+## projects
+
+### `client.projects.list(params)`
+
+List projects
+
+`GET /projects`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<Project>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+### `client.projects.create(body, params)`
+
+Create a project
+
+`POST /projects`
+
+Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected output, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and the whole spec.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `idempotencyKey` | header | `string` | no | Uniquely identifies this creation attempt. Retrying the same request with the same key returns the original response instead of creating another project. Reusing a key with different parameters returns 409. |
+
+Body: `CreateProjectRequest` (required)
+
+Returns: `Project`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `ConflictError` (409), `RateLimitedError` (429), `InternalServerError` (500)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "name": "example",
+  "source": {
+    "kind": "url",
+    "url": "https://example.com"
+  },
+  "outputs": [
+    "typescript-sdk"
+  ]
+}
+```
+
+</details>
+
+### `client.projects.retrieve(projectId)`
+
+Retrieve a project
+
+`GET /projects/{project_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `Project`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.delete(projectId)`
+
+Delete a project
+
+`DELETE /projects/{project_id}`
+
+Safety: **destructive** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `DeletedProject`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.update(projectId, body)`
+
+Update a project
+
+`PATCH /projects/{project_id}`
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Body: `UpdateProjectRequest` (required)
+
+Returns: `Project`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.retrieveGithubHealth(projectId)`
+
+Diagnose a project's GitHub integration
+
+`GET /projects/{project_id}/github`
+
+Returns machine-actionable source and destination access, spec readability, optional label setup, required status names, and the latest durable webhook delivery. The console renders this same result.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `GithubIntegrationHealth`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.listGenerations(projectId, params)`
+
+List a project's generations
+
+`GET /projects/{project_id}/generations`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `output` | query | `OutputId` | no | Only generations for this output. |
+
+Returns: `PagePromise<Generation>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.generate(projectId)`
+
+Generate outputs and open pull requests
+
+`POST /projects/{project_id}/generations`
+
+Resolves the project's URL or repository source, generates every
+configured delivery package, stores each result in the project's history,
+and attempts to open a pull request in every configured destination.
+When the complete generated tree already matches a destination, no
+commit, branch, or pull request is created and that generation reports
+`pr_status: no_changes`. This is the same pipeline automatic
+regeneration runs after a source change.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `GenerationBatch`
+Errors: `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+## generations
+
+### `client.generations.retrieve(generationId)`
+
+Retrieve a generation
+
+`GET /generations/{generation_id}`
+
+Includes the generated files when the generation succeeded.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `generationId` | path | `GenerationId` | yes | — |
+
+Returns: `Generation`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "generation_id": "gen_7h2p5d9c3m8w1k6q"
+}
+```
+
+</details>
+
+### `client.generations.retrieveFile(generationId, params)`
+
+Fetch one file from a generation
+
+`GET /generations/{generation_id}/file`
+
+Raw file content, for generations whose output was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `generationId` | path | `GenerationId` | yes | — |
+| `path` | query | `string` | yes | Repo-relative path inside the generated package. |
+
+Returns: `string`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "generation_id": "gen_7h2p5d9c3m8w1k6q",
+  "path": "openapi.yaml"
+}
+```
+
+</details>
+
+## specRevisions
+
+### `client.specRevisions.list(projectId, params)`
+
+List specification revisions
+
+`GET /projects/{project_id}/spec_revisions`
+
+Immutable snapshots of the exact source text this project consumed, newest first. Raw content is available from each revision's content endpoint and is never embedded in a list response.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<SpecRevision>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.specRevisions.retrieve(specRevisionId)`
+
+Retrieve a specification revision
+
+`GET /spec_revisions/{spec_revision_id}`
+
+Metadata for one immutable source snapshot. Fetch raw source text from the content endpoint so metadata responses stay small and predictable.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+
+Returns: `SpecRevision`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+}
+```
+
+</details>
+
+### `client.specRevisions.retrieveContent(specRevisionId)`
+
+Retrieve a specification revision's raw text
+
+`GET /spec_revisions/{spec_revision_id}/content`
+
+Returns the exact source text identified by the revision's SHA-256 digest, suitable for saving or piping directly into a diff.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+
+Returns: `string`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+}
+```
+
+</details>
+
+## account
+
+### `client.account.retrieve()`
+
+The account behind the presented credentials
+
+`GET /me`
+
+Returns the account that owns the presented API key. This is also the
+identity endpoint the generated typeship CLI's `whoami` calls.
+
+Safety: **read** · Authentication: **required**
+
+Returns: `Account`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+## apiKeys
+
+### `client.apiKeys.list(params)`
+
+List API keys
+
+`GET /api_keys`
+
+Keys are never returned in full — only their identity and last four. Creation stays in the console deliberately: a leaked key that can mint more keys is a leaked account.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<ApiKey>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+### `client.apiKeys.revoke(apiKeyId)`
+
+Revoke an API key
+
+`DELETE /api_keys/{api_key_id}`
+
+Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded.
+
+Safety: **destructive** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `apiKeyId` | path | `string` | yes | — |
+
+Returns: `ApiKey`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "api_key_id": "api_key_123"
+}
+```
+
+</details>