@amos.com/node 0.1.0 → 0.1.1
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 +63 -106
- package/dist/index.d.mts +4452 -0
- package/dist/index.d.ts +4452 -0
- package/dist/index.js +53 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +15 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -1,23 +1,33 @@
|
|
|
1
1
|
# Amos
|
|
2
2
|
|
|
3
|
-
A typed Node.js client for the **Amos Pay** API, generated from the
|
|
3
|
+
A typed Node.js client for the **Amos Pay** API, generated from the OpenAPI spec with [`openapi-typescript`](https://openapi-ts.dev/) and powered by [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch).
|
|
4
4
|
|
|
5
5
|
> **Docs:** the full Amos API reference lives at [docs.amos.com](https://docs.amos.com/). This package is the typed Node.js binding for that API.
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npm install amos
|
|
10
|
+
npm install @amos.com/node
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
## Quick start
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
-
import
|
|
17
|
-
|
|
18
|
-
|
|
16
|
+
import {
|
|
17
|
+
createPayApiClient,
|
|
18
|
+
PAY_API_BASE_URL_PRODUCTION,
|
|
19
|
+
PAY_API_VERSION,
|
|
20
|
+
} from "@amos.com/node";
|
|
21
|
+
|
|
22
|
+
const pay = createPayApiClient({
|
|
23
|
+
baseUrl: PAY_API_BASE_URL_PRODUCTION,
|
|
24
|
+
headers: {
|
|
25
|
+
"X-Api-Key": process.env.AMOS_API_KEY!,
|
|
26
|
+
"X-Api-Version": PAY_API_VERSION,
|
|
27
|
+
},
|
|
28
|
+
});
|
|
19
29
|
|
|
20
|
-
const { data, error } = await
|
|
30
|
+
const { data, error } = await pay.POST("/customers", {
|
|
21
31
|
body: { customer: { email: "alex@example.com" } },
|
|
22
32
|
});
|
|
23
33
|
|
|
@@ -30,24 +40,44 @@ if (error) {
|
|
|
30
40
|
|
|
31
41
|
### Sandbox mode
|
|
32
42
|
|
|
43
|
+
Swap the base URL constant:
|
|
44
|
+
|
|
33
45
|
```ts
|
|
34
|
-
|
|
46
|
+
import {
|
|
47
|
+
createPayApiClient,
|
|
48
|
+
PAY_API_BASE_URL_SANDBOX,
|
|
49
|
+
PAY_API_VERSION,
|
|
50
|
+
} from "@amos.com/node";
|
|
51
|
+
|
|
52
|
+
const pay = createPayApiClient({
|
|
53
|
+
baseUrl: PAY_API_BASE_URL_SANDBOX,
|
|
54
|
+
headers: {
|
|
55
|
+
"X-Api-Key": process.env.AMOS_API_KEY!,
|
|
56
|
+
"X-Api-Version": PAY_API_VERSION,
|
|
57
|
+
},
|
|
58
|
+
});
|
|
35
59
|
```
|
|
36
60
|
|
|
37
61
|
### Custom base URL or fetch
|
|
38
62
|
|
|
63
|
+
`createPayApiClient` accepts any of [`openapi-fetch`'s `ClientOptions`](https://openapi-ts.dev/openapi-fetch/api#create-client), so you can point at a proxy or supply your own `fetch`:
|
|
64
|
+
|
|
39
65
|
```ts
|
|
40
|
-
const
|
|
66
|
+
const pay = createPayApiClient({
|
|
41
67
|
baseUrl: "https://my-proxy.example.com",
|
|
42
68
|
fetch: customFetchImpl,
|
|
43
|
-
headers: {
|
|
69
|
+
headers: {
|
|
70
|
+
"X-Api-Key": process.env.AMOS_API_KEY!,
|
|
71
|
+
"X-Api-Version": PAY_API_VERSION,
|
|
72
|
+
"X-Trace-Id": "abc123",
|
|
73
|
+
},
|
|
44
74
|
});
|
|
45
75
|
```
|
|
46
76
|
|
|
47
77
|
### Middleware (e.g. fresh idempotency keys)
|
|
48
78
|
|
|
49
79
|
```ts
|
|
50
|
-
import type { Middleware } from "amos";
|
|
80
|
+
import type { Middleware } from "@amos.com/node";
|
|
51
81
|
|
|
52
82
|
const idempotencyKey: Middleware = {
|
|
53
83
|
async onRequest({ request }) {
|
|
@@ -58,34 +88,33 @@ const idempotencyKey: Middleware = {
|
|
|
58
88
|
},
|
|
59
89
|
};
|
|
60
90
|
|
|
61
|
-
|
|
91
|
+
pay.use(idempotencyKey);
|
|
62
92
|
```
|
|
63
93
|
|
|
64
94
|
## API surface
|
|
65
95
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
96
|
+
```ts
|
|
97
|
+
import {
|
|
98
|
+
createPayApiClient,
|
|
99
|
+
PAY_API_BASE_URL_PRODUCTION,
|
|
100
|
+
PAY_API_BASE_URL_SANDBOX,
|
|
101
|
+
PAY_API_VERSION,
|
|
102
|
+
} from "@amos.com/node";
|
|
103
|
+
import type { PayApiClient, ClientOptions, Middleware } from "@amos.com/node";
|
|
104
|
+
```
|
|
73
105
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
| `headers` | `Record<string, string>` | `{}` | Additional default headers merged into every request. |
|
|
80
|
-
| `fetch` | `typeof fetch` | global `fetch` | Custom `fetch` implementation. |
|
|
81
|
-
| `clientOptions` | `Partial<ClientOptions>` | `{}` | Escape hatch for any other `openapi-fetch` client options. |
|
|
106
|
+
- `createPayApiClient(options)` — returns a typed [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch) client. Exposes the full `openapi-fetch` interface: `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `HEAD`, `PATCH`, `TRACE`, `use`, `eject`.
|
|
107
|
+
- `PAY_API_BASE_URL_PRODUCTION` / `PAY_API_BASE_URL_SANDBOX` — base URLs for the two environments.
|
|
108
|
+
- `PAY_API_VERSION` — the wire-level `X-Api-Version` this build targets. Pass it as the `X-Api-Version` header on every request (most easily as a default in `headers`, as shown above).
|
|
109
|
+
- `PayApiClient` — the type returned by `createPayApiClient`.
|
|
110
|
+
- `ClientOptions`, `Middleware` — re-exported from `openapi-fetch` for convenience.
|
|
82
111
|
|
|
83
112
|
## Types
|
|
84
113
|
|
|
85
114
|
All schema types are re-exported from the main entry. For example:
|
|
86
115
|
|
|
87
116
|
```ts
|
|
88
|
-
import type { components, paths, operations } from "amos";
|
|
117
|
+
import type { components, paths, operations } from "@amos.com/node";
|
|
89
118
|
|
|
90
119
|
type Customer = components["schemas"]["Customer"];
|
|
91
120
|
```
|
|
@@ -94,85 +123,13 @@ type Customer = components["schemas"]["Customer"];
|
|
|
94
123
|
|
|
95
124
|
We follow **SemVer** for the npm package, with one extra rule: **the major version tracks the wire-level `X-Api-Version` header**.
|
|
96
125
|
|
|
97
|
-
| npm range
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
102
|
-
So bumping `DEFAULT_API_VERSION` in `src/index.ts` is always a major release, and consumers who pin to `amos@^1` know they will never be transparently upgraded onto a new wire contract.
|
|
103
|
-
|
|
104
|
-
> **Pre-1.0 caveat.** While we're on `0.x`, **breaking changes can land in any `0.x` release.** Strict SemVer (and the API-version-tracks-major rule above) starts the day we cut `1.0.0`. Pin to an exact `0.x.y` if you need stability today.
|
|
105
|
-
|
|
106
|
-
### How spec changes map to bumps
|
|
107
|
-
|
|
108
|
-
The package is essentially "OpenAPI-derived types + a thin runtime wrapper", so we classify changes by their TypeScript-visible impact:
|
|
109
|
-
|
|
110
|
-
| Change in the spec or runtime | Bump |
|
|
111
|
-
| ------------------------------------------------------------------------------------------------------------ | ----- |
|
|
112
|
-
| Removing/renaming a path, operation, schema, or response enum value | major |
|
|
113
|
-
| Narrowing a type, making a request field required, changing a parameter from optional to required | major |
|
|
114
|
-
| Changing the `Amos` constructor surface in a breaking way, or bumping `DEFAULT_API_VERSION` | major |
|
|
115
|
-
| Adding endpoints, schemas, optional request fields, request enum values, or new runtime exports | minor |
|
|
116
|
-
| Spec descriptions/examples/tags only, internal refactors with no public type change, dependency-only updates | patch |
|
|
117
|
-
|
|
118
|
-
The mental rule: _"would a program that typechecked against the previous `dist/index.d.ts` still typecheck against the new one?"_ If no, it's a major.
|
|
119
|
-
|
|
120
|
-
### Spec source of truth, not `info.version`
|
|
121
|
-
|
|
122
|
-
The npm version in `package.json` is **decoupled** from the `info.version` field of the upstream OpenAPI spec. They drift independently on purpose: a docs-only spec edit shouldn't ship an SDK release, and an SDK-only fix shouldn't wait for a spec change.
|
|
123
|
-
|
|
124
|
-
What we _do_ track per release is the upstream commit SHA, in two places:
|
|
126
|
+
| npm range | `X-Api-Version` it targets |
|
|
127
|
+
| -------------------- | -------------------------- |
|
|
128
|
+
| `@amos.com/node@1.x` | `1` |
|
|
129
|
+
| `@amos.com/node@2.x` | `2` (hypothetical) |
|
|
125
130
|
|
|
126
|
-
|
|
127
|
-
- `CHANGELOG.md` — every release entry references the upstream `amos/openapi` commit(s) that produced it (auto-populated by the regeneration workflow, see below).
|
|
131
|
+
So bumping `PAY_API_VERSION` is always a major release, and consumers who pin to `@amos.com/node@^1` know they will never be transparently upgraded onto a new wire contract.
|
|
128
132
|
|
|
129
|
-
|
|
133
|
+
The mental rule for bumps: _"would a program that typechecked against the previous `dist/index.d.ts` still typecheck against the new one?"_ If no, it's a major.
|
|
130
134
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
### Path A: regenerated from the OpenAPI spec (the common case)
|
|
134
|
-
|
|
135
|
-
1. The [`Regenerate from OpenAPI`](./.github/workflows/regenerate.yml) workflow runs on `workflow_dispatch`, or when the OpenAPI source repo fires a `repository_dispatch` event of type `public-openapi-spec-updated` (dispatched by the upstream sync workflow whenever the public spec changes on its `main`).
|
|
136
|
-
2. It checks out the spec repo at the dispatched commit, diffs that spec against the SHA recorded in [`openapi/source.json`](./openapi/source.json) using [`oasdiff`](https://github.com/oasdiff/oasdiff), and classifies the change as `major` / `minor` / `patch`.
|
|
137
|
-
3. If anything changed, it regenerates `openapi/schema.ts` (via `npm run build`), updates `openapi/source.json`, writes a `.changeset/regen-<sha>.md` file with the recommended bump and the upstream commit log, and opens a PR.
|
|
138
|
-
4. A maintainer reviews the PR — **adjust the bump in the changeset file if `oasdiff` misclassified anything** (e.g., a response-only enum addition that breaks exhaustive switches in your consumers should be promoted to `major`) — and merges.
|
|
139
|
-
5. The [`Release`](./.github/workflows/release.yml) workflow then opens or updates a "Version Packages" PR. Merging that PR publishes to npm and tags the commit.
|
|
140
|
-
|
|
141
|
-
### Path B: hand-authored change (runtime fix, refactor, dep bump)
|
|
142
|
-
|
|
143
|
-
1. Make your change on a branch.
|
|
144
|
-
2. Run `npx changeset` and answer the prompts to describe the bump.
|
|
145
|
-
3. Open a PR. Reviewers will see the changeset file alongside the diff.
|
|
146
|
-
4. Merging triggers the same `Release` workflow as above.
|
|
147
|
-
|
|
148
|
-
### Required CI secrets
|
|
149
|
-
|
|
150
|
-
| Secret | Used by | Purpose |
|
|
151
|
-
| -------------------- | ---------------- | ----------------------------------------------------------------------------- |
|
|
152
|
-
| `NPM_TOKEN` | `release.yml` | Publishing to npm. Use an automation token from the `amos` org/account. |
|
|
153
|
-
| `OPENAPI_REPO_TOKEN` | `regenerate.yml` | Fine-grained PAT with `Contents: Read` on `amos/openapi`. Spec is private. |
|
|
154
|
-
|
|
155
|
-
The default `GITHUB_TOKEN` handles everything else. Make sure **Settings -> Actions -> General -> Workflow permissions -> "Allow GitHub Actions to create and approve pull requests"** is enabled so the regenerate workflow can open PRs.
|
|
156
|
-
|
|
157
|
-
## Regenerating locally
|
|
158
|
-
|
|
159
|
-
If you want to preview a regeneration without going through CI:
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
npm run generate
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
This pulls the sibling `../openapi` checkout and rewrites `openapi/schema.ts`. It does **not** touch `openapi/source.json` or write a changeset — only the workflow does that, so the recorded SHA always matches a released version.
|
|
166
|
-
|
|
167
|
-
## Development
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
npm install
|
|
171
|
-
npm run build
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
Add a changeset alongside any user-visible change:
|
|
175
|
-
|
|
176
|
-
```bash
|
|
177
|
-
npx changeset
|
|
178
|
-
```
|
|
135
|
+
> **Pre-1.0 caveat.** While we're on `0.x`, **breaking changes can land in any `0.x` release.** Strict SemVer (and the API-version-tracks-major rule above) starts the day we cut `1.0.0`. Pin to an exact `0.x.y` if you need stability today.
|