gatana-sdk 3.1.2 → 3.1.3

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.
Files changed (2) hide show
  1. package/README.md +142 -0
  2. package/package.json +4 -4
package/README.md ADDED
@@ -0,0 +1,142 @@
1
+ # gatana-sdk
2
+
3
+ [![npm](https://img.shields.io/npm/v/gatana-sdk)](https://www.npmjs.com/package/gatana-sdk)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+
6
+ JavaScript and TypeScript SDK for the [Gatana](https://gatana.ai) API. It is generated from the
7
+ backend's OpenAPI documents with [`@hey-api/openapi-ts`](https://heyapi.dev), and adds the loading
8
+ of the credentials.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm install gatana-sdk
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```typescript
19
+ import { Gatana } from 'gatana-sdk';
20
+
21
+ // Reads GATANA_API_KEY and GATANA_ORG_ID, or ~/.gatana.config
22
+ const client = new Gatana();
23
+
24
+ const { data: servers } = await client.api.listMcpServers();
25
+ ```
26
+
27
+ Each operation of the API is a function on `client.api`. A call returns `{ data, request, response }`
28
+ and throws when the response is an error.
29
+
30
+ The SDK finds the credentials in the same way as the CLI. See
31
+ [Configuration](https://github.com/gatana-ai/gatana#configuration) for the environment variables and
32
+ the config file. Run `gatana config login <org>` to write the config file. The SDK refreshes expired
33
+ OIDC tokens from that file and writes the new tokens back.
34
+
35
+ ### Custom authentication
36
+
37
+ Give the credentials in code:
38
+
39
+ ```typescript
40
+ import { Gatana } from 'gatana-sdk';
41
+
42
+ // An API key or a personal access token, and an organization ID or a base URL
43
+ const client = new Gatana({ options: { apiKey: 'gk_...', orgId: 'my-org' } });
44
+ ```
45
+
46
+ Give a token function, for example to read the token from a vault:
47
+
48
+ ```typescript
49
+ const client = new Gatana({
50
+ config: {
51
+ baseUrl: 'https://my-org.gatana.ai',
52
+ token: async () => readTokenFromVault(),
53
+ },
54
+ });
55
+ ```
56
+
57
+ Or select the strategies, in the order you want:
58
+
59
+ ```typescript
60
+ import { Gatana, ConfigLoader, EnvConfigStrategy, FileConfigStrategy } from 'gatana-sdk';
61
+
62
+ // Use the environment, then the "other-org" entry of ~/.gatana.config
63
+ const client = new Gatana({
64
+ configLoader: new ConfigLoader([new EnvConfigStrategy(), new FileConfigStrategy('other-org')]),
65
+ });
66
+ ```
67
+
68
+ ### V2 API client
69
+
70
+ `Gatana2` is the client for the v2 API at `/api/v2/`. In this API, you can send the object that a
71
+ GET returns back in a POST, PUT or PATCH request.
72
+
73
+ ```typescript
74
+ import { Gatana2 } from 'gatana-sdk';
75
+
76
+ const client = new Gatana2();
77
+ const { data: servers } = await client.api.listServersV2();
78
+ ```
79
+
80
+ `Gatana2` takes the same constructor arguments as `Gatana`.
81
+
82
+ ### Exports
83
+
84
+ | Export | Description |
85
+ | ----------------------- | ------------------------------------------------------------- |
86
+ | `Gatana` | V1 API client. Wraps the generated SDK at `/api/v1/` |
87
+ | `Gatana2` | V2 API client. REST-style API at `/api/v2/` |
88
+ | `ConfigLoader` | Tries the config strategies in order |
89
+ | `ConfigStrategy` | Abstract base class for a config strategy |
90
+ | `OptionsConfigStrategy` | Credentials from `{ apiKey, orgId }` or `{ apiKey, baseUrl }` |
91
+ | `EnvConfigStrategy` | Credentials from environment variables |
92
+ | `FileConfigStrategy` | Credentials from `~/.gatana.config`, with token refresh |
93
+
94
+ Subpath exports:
95
+
96
+ | Import | What it holds |
97
+ | ------------------- | ------------------------------------------------ |
98
+ | `gatana-sdk/api` | The generated v1 functions and types |
99
+ | `gatana-sdk/apiv2` | The generated v2 functions and types |
100
+ | `gatana-sdk/config` | Functions that read and write `~/.gatana.config` |
101
+
102
+ ### Debugging
103
+
104
+ The SDK logs with the [`debug`](https://www.npmjs.com/package/debug) package:
105
+
106
+ ```bash
107
+ # General debug output
108
+ DEBUG=gatana node your-script.js
109
+
110
+ # HTTP requests and responses
111
+ DEBUG=gatana:http node your-script.js
112
+ ```
113
+
114
+ ## Development
115
+
116
+ Run these from the repository root.
117
+
118
+ ```bash
119
+ just install # install the dependencies
120
+ just build # build the SDK into packages/gatana-js/dist
121
+ just dev # build again on each change
122
+ just generate # regenerate the v1 and v2 clients from the OpenAPI documents, then build
123
+ just pack # build and pack the SDK, without publishing
124
+ just fmt # format with prettier
125
+ ```
126
+
127
+ `gensdk.ts` runs the generator on the OpenAPI documents of `hello.gatana.ai`. To use a local
128
+ backend, set `OVERRIDE_OPENAPI_URL` to its v1 document, for example
129
+ `https://acme.local.gatana.ai/api/v1/openapi.json`. Do not edit the files in
130
+ `src/api/` and `src/apiv2/` by hand: `just generate` overwrites them. The hand-written code is in
131
+ `src/index.ts`, `src/v2.ts` and `src/config.ts`.
132
+
133
+ ### Releasing
134
+
135
+ `just release` in the repository root releases every package with changes, this one included. To
136
+ release only this package, run `just js-release`. It checks the npm login, asks for the version bump,
137
+ builds, publishes to npm, and tags `gatana-sdk@<version>`. The GitHub release is not marked as
138
+ latest, because `releases/latest` belongs to the CLI.
139
+
140
+ ## License
141
+
142
+ [MIT](https://github.com/gatana-ai/gatana/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "gatana-sdk",
3
- "version": "3.1.2",
3
+ "version": "3.1.3",
4
4
  "description": "Javascript/Typescript SDK for Gatana",
5
- "homepage": "https://github.com/gatana-ai/gatana-js#readme",
5
+ "homepage": "https://github.com/gatana-ai/gatana/tree/main/packages/gatana-js#readme",
6
6
  "bugs": {
7
- "url": "https://github.com/gatana-ai/gatana-js/issues"
7
+ "url": "https://github.com/gatana-ai/gatana/issues"
8
8
  },
9
9
  "repository": {
10
10
  "type": "git",
11
- "url": "git+https://github.com/gatana-ai/gatana-js.git",
11
+ "url": "git+https://github.com/gatana-ai/gatana.git",
12
12
  "directory": "packages/gatana-js"
13
13
  },
14
14
  "license": "MIT",