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.
- package/README.md +142 -0
- package/package.json +4 -4
package/README.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# gatana-sdk
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/gatana-sdk)
|
|
4
|
+
[](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.
|
|
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
|
|
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
|
|
11
|
+
"url": "git+https://github.com/gatana-ai/gatana.git",
|
|
12
12
|
"directory": "packages/gatana-js"
|
|
13
13
|
},
|
|
14
14
|
"license": "MIT",
|