@tracken/cli 0.0.0-stage → 0.2.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.
Files changed (143) hide show
  1. package/CHANGELOG.md +404 -0
  2. package/LICENSE +21 -0
  3. package/README.md +310 -2
  4. package/dist/bin/tracken.d.ts +2 -0
  5. package/dist/bin/tracken.js +5 -0
  6. package/dist/cli/args.d.ts +17 -0
  7. package/dist/cli/args.js +114 -0
  8. package/dist/cli/commands/api.d.ts +2 -0
  9. package/dist/cli/commands/api.js +73 -0
  10. package/dist/cli/commands/auth.d.ts +8 -0
  11. package/dist/cli/commands/auth.js +141 -0
  12. package/dist/cli/commands/mcp.d.ts +19 -0
  13. package/dist/cli/commands/mcp.js +89 -0
  14. package/dist/cli/commands/org.d.ts +24 -0
  15. package/dist/cli/commands/org.js +123 -0
  16. package/dist/cli/context.d.ts +54 -0
  17. package/dist/cli/context.js +135 -0
  18. package/dist/cli/execute.d.ts +16 -0
  19. package/dist/cli/execute.js +112 -0
  20. package/dist/cli/help.d.ts +8 -0
  21. package/dist/cli/help.js +153 -0
  22. package/dist/cli/main.d.ts +2 -0
  23. package/dist/cli/main.js +114 -0
  24. package/dist/cli/operation-args.d.ts +25 -0
  25. package/dist/cli/operation-args.js +245 -0
  26. package/dist/core/auth/oauth.d.ts +39 -0
  27. package/dist/core/auth/oauth.js +102 -0
  28. package/dist/core/auth/scopes.d.ts +19 -0
  29. package/dist/core/auth/scopes.js +49 -0
  30. package/dist/core/auth/secret-store.d.ts +60 -0
  31. package/dist/core/auth/secret-store.js +141 -0
  32. package/dist/core/auth/session.d.ts +75 -0
  33. package/dist/core/auth/session.js +200 -0
  34. package/dist/core/catalog.d.ts +12 -0
  35. package/dist/core/catalog.js +33 -0
  36. package/dist/core/client.d.ts +22 -0
  37. package/dist/core/client.js +45 -0
  38. package/dist/core/config.d.ts +27 -0
  39. package/dist/core/config.js +109 -0
  40. package/dist/core/environments.d.ts +21 -0
  41. package/dist/core/environments.js +53 -0
  42. package/dist/core/errors.d.ts +96 -0
  43. package/dist/core/errors.js +248 -0
  44. package/dist/core/index.d.ts +21 -0
  45. package/dist/core/index.js +22 -0
  46. package/dist/core/jobs.d.ts +15 -0
  47. package/dist/core/jobs.js +19 -0
  48. package/dist/core/operations.d.ts +108 -0
  49. package/dist/core/operations.js +7 -0
  50. package/dist/core/output/format.d.ts +19 -0
  51. package/dist/core/output/format.js +62 -0
  52. package/dist/core/output/render.d.ts +53 -0
  53. package/dist/core/output/render.js +229 -0
  54. package/dist/core/pagination.d.ts +2 -0
  55. package/dist/core/pagination.js +3 -0
  56. package/dist/core/request.d.ts +29 -0
  57. package/dist/core/request.js +109 -0
  58. package/dist/core/version.d.ts +10 -0
  59. package/dist/core/version.js +13 -0
  60. package/dist/generated/mcp-tools.d.ts +2 -0
  61. package/dist/generated/mcp-tools.js +5937 -0
  62. package/dist/generated/operations.d.ts +4 -0
  63. package/dist/generated/operations.js +17701 -0
  64. package/dist/mcp/errors.d.ts +34 -0
  65. package/dist/mcp/errors.js +100 -0
  66. package/dist/mcp/live.d.ts +3 -0
  67. package/dist/mcp/live.js +5 -0
  68. package/dist/mcp/prompts.d.ts +23 -0
  69. package/dist/mcp/prompts.js +101 -0
  70. package/dist/mcp/resources.d.ts +25 -0
  71. package/dist/mcp/resources.js +125 -0
  72. package/dist/mcp/server.d.ts +20 -0
  73. package/dist/mcp/server.js +59 -0
  74. package/dist/mcp/session.d.ts +60 -0
  75. package/dist/mcp/session.js +105 -0
  76. package/dist/mcp/tools.d.ts +17 -0
  77. package/dist/mcp/tools.js +181 -0
  78. package/dist/mcp/types.d.ts +25 -0
  79. package/dist/mcp/types.js +2 -0
  80. package/node_modules/@tracken/sdk/LICENSE +21 -0
  81. package/node_modules/@tracken/sdk/README.md +76 -0
  82. package/node_modules/@tracken/sdk/SOURCE.json +10 -0
  83. package/node_modules/@tracken/sdk/dist/client.d.ts +94 -0
  84. package/node_modules/@tracken/sdk/dist/client.js +258 -0
  85. package/node_modules/@tracken/sdk/dist/credentials.d.ts +60 -0
  86. package/node_modules/@tracken/sdk/dist/credentials.js +122 -0
  87. package/node_modules/@tracken/sdk/dist/decimal.d.ts +20 -0
  88. package/node_modules/@tracken/sdk/dist/decimal.js +67 -0
  89. package/node_modules/@tracken/sdk/dist/environments.d.ts +14 -0
  90. package/node_modules/@tracken/sdk/dist/environments.js +16 -0
  91. package/node_modules/@tracken/sdk/dist/errors.d.ts +150 -0
  92. package/node_modules/@tracken/sdk/dist/errors.js +190 -0
  93. package/node_modules/@tracken/sdk/dist/generated/operations.d.ts +1955 -0
  94. package/node_modules/@tracken/sdk/dist/generated/operations.js +2746 -0
  95. package/node_modules/@tracken/sdk/dist/generated/schema.d.ts +17988 -0
  96. package/node_modules/@tracken/sdk/dist/generated/schema.js +5 -0
  97. package/node_modules/@tracken/sdk/dist/index.d.ts +27 -0
  98. package/node_modules/@tracken/sdk/dist/index.js +24 -0
  99. package/node_modules/@tracken/sdk/dist/jobs.d.ts +23 -0
  100. package/node_modules/@tracken/sdk/dist/jobs.js +80 -0
  101. package/node_modules/@tracken/sdk/dist/operations.d.ts +23 -0
  102. package/node_modules/@tracken/sdk/dist/operations.js +2 -0
  103. package/node_modules/@tracken/sdk/dist/pagination.d.ts +19 -0
  104. package/node_modules/@tracken/sdk/dist/pagination.js +49 -0
  105. package/node_modules/@tracken/sdk/dist/request.d.ts +27 -0
  106. package/node_modules/@tracken/sdk/dist/request.js +10 -0
  107. package/node_modules/@tracken/sdk/dist/runtime.d.ts +22 -0
  108. package/node_modules/@tracken/sdk/dist/runtime.js +33 -0
  109. package/node_modules/@tracken/sdk/dist/tracken.d.ts +74 -0
  110. package/node_modules/@tracken/sdk/dist/tracken.js +203 -0
  111. package/node_modules/@tracken/sdk/dist/types.d.ts +130 -0
  112. package/node_modules/@tracken/sdk/dist/types.js +1 -0
  113. package/node_modules/@tracken/sdk/dist/version.d.ts +2 -0
  114. package/node_modules/@tracken/sdk/dist/version.js +2 -0
  115. package/node_modules/@tracken/sdk/package.json +42 -0
  116. package/node_modules/openapi-fetch/CHANGELOG.md +565 -0
  117. package/node_modules/openapi-fetch/CONTRIBUTING.md +102 -0
  118. package/node_modules/openapi-fetch/LICENSE +21 -0
  119. package/node_modules/openapi-fetch/README.md +122 -0
  120. package/node_modules/openapi-fetch/dist/index.cjs +547 -0
  121. package/node_modules/openapi-fetch/dist/index.cjs.map +1 -0
  122. package/node_modules/openapi-fetch/dist/index.d.cts +337 -0
  123. package/node_modules/openapi-fetch/dist/index.d.mts +335 -0
  124. package/node_modules/openapi-fetch/dist/index.d.ts +337 -0
  125. package/node_modules/openapi-fetch/dist/index.mjs +531 -0
  126. package/node_modules/openapi-fetch/dist/index.mjs.map +1 -0
  127. package/node_modules/openapi-fetch/package.json +77 -0
  128. package/node_modules/openapi-fetch/src/index.d.ts +345 -0
  129. package/node_modules/openapi-fetch/src/index.js +689 -0
  130. package/node_modules/openapi-typescript-helpers/CHANGELOG.md +98 -0
  131. package/node_modules/openapi-typescript-helpers/LICENSE +21 -0
  132. package/node_modules/openapi-typescript-helpers/README.md +5 -0
  133. package/node_modules/openapi-typescript-helpers/dist/index.cjs +3 -0
  134. package/node_modules/openapi-typescript-helpers/dist/index.cjs.map +1 -0
  135. package/node_modules/openapi-typescript-helpers/dist/index.d.cts +167 -0
  136. package/node_modules/openapi-typescript-helpers/dist/index.d.mts +167 -0
  137. package/node_modules/openapi-typescript-helpers/dist/index.d.ts +167 -0
  138. package/node_modules/openapi-typescript-helpers/dist/index.mjs +2 -0
  139. package/node_modules/openapi-typescript-helpers/dist/index.mjs.map +1 -0
  140. package/node_modules/openapi-typescript-helpers/package.json +39 -0
  141. package/openapi/SOURCE.json +10 -0
  142. package/openapi/openapi.yaml +30514 -0
  143. package/package.json +63 -4
@@ -0,0 +1,102 @@
1
+ # Contributing
2
+
3
+ Thanks for being willing to contribute! 🙏
4
+
5
+ **Working on your first Pull Request (PR)?** You can learn how from this free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).
6
+
7
+ ## Open issues
8
+
9
+ Please check out the [the open issues](https://github.com/openapi-ts/openapi-typescript/issues). Issues labelled [**Good First Issue**](https://github.com/openapi-ts/openapi-typescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are especially good to start with.
10
+
11
+ Contributing doesn’t have to be in code. Simply answering questions in open issues or providing workarounds is as important as making pull requests.
12
+
13
+ ## Writing code
14
+
15
+ ### Setup
16
+
17
+ 1. Install [pnpm](https://pnpm.io/)
18
+ 2. [Fork this repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your copy locally
19
+ 3. Run `pnpm i` to install dependencies
20
+
21
+ ### Runtime code vs static type declarations
22
+
23
+ This project uses **manual type declarations** ([docs](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#dts-files)) that are kept separately from the runtime code. `index.d.ts` contains **type declarations**, and `index.js` contains **runtime code**. The most important code lives in `index.d.ts` because this library exists to provide correct type inference. `index.js`, is far less important, and is only doing bare-minimum work to support the API as efficiently as possible.
24
+
25
+ In most projects, **this is not recommended practice** as the two can (and will) diverge, and you’re left with types that “lie” to you about what the runtime is doing. So this project does have that liability. However, due to the unique nature of this project implementing complex type inference from user-provided schemas, the type inference itself is so complex it was interfering with readable, maintainable, runtime code. By separating the two we won’t have the more complex parts of TypeScript interfering with the optimal runtime code. This would not be tenable in a larger project, but is perfect for a small codebase like this with minimal surface area.
26
+
27
+ When writing code, it’s tempting to ignore `index.d.ts` and only make runtime updates, since that is generally simpler. But **please don’t!** We write tests in `*.test.ts` files intentionally so that the type inference can be typechecked as well as the runtime. Whenever you make a change to `index.js`, you probably need to also make a chance to `index.d.ts`, too. And **testing type correctness in tests is just as important as testing the runtime!**
28
+
29
+ ### Testing
30
+
31
+ This library uses [Vitest](https://vitest.dev/) for testing. There’s a great [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) you can optionally use if you’d like in-editor debugging tools.
32
+
33
+ To run the entire test suite, run:
34
+
35
+ ```sh
36
+ pnpm test
37
+ ```
38
+
39
+ To run an individual test:
40
+
41
+ ```sh
42
+ pnpm test -- [partial filename]
43
+ ```
44
+
45
+ To start the entire test suite in watch mode:
46
+
47
+ ```sh
48
+ npx vitest
49
+ ```
50
+
51
+ #### Important test-writing tips
52
+
53
+ All tests in this project should adhere to the following rules:
54
+
55
+ 1. **Use `assertType<T>(…)`** ([docs](https://vitest.dev/guide/testing-types)). Don’t just check the _actual_ runtime value; check the _perceived_ type as well.
56
+ 2. **Testing TS errors is just as important as testing for expected types.** Use `// @ts-expected-error` liberally. this is discouraged because it’s hiding an error. But in our tests, we **want** to test that a TS error is thrown for invalid input.
57
+ 3. **Scope `// @ts-expect-error` as closely as possible.** Remember that JS largely ignores whitespace. When using `// @ts-expect-error`, try and break up an expression into as many lines as possible, so that the `// @ts-expect-error` is scoped to the right line. Otherwise it is possible a _different part of the expression_ is throwing the error!
58
+ 4. **Manually type out type tests.** Avoid using [test.each](https://vitest.dev/api/#test-each) for type tests, as it’s likely hiding errors.
59
+
60
+ ### Linting
61
+
62
+ Linting is handled via [Biome](https://biomejs.dev), a faster ESLint replacement. It was installed with `pnpm i` and can be run with:
63
+
64
+ ```sh
65
+ pnpm run lint
66
+ ```
67
+
68
+ ### Changelogs
69
+
70
+ The changelog is generated via [changesets](https://github.com/changesets/changesets), and is separate from Git commit messages and pull request titles. To write a human-readable changelog for your changes, run:
71
+
72
+ ```
73
+ npx changeset
74
+ ```
75
+
76
+ This will ask if it’s a `patch`, `minor`, or `major` change ([semver](https://semver.org/)), along with a plain description of what you did. Commit this new file along with the rest of your PR, and during the next release this will go into the official changelog!
77
+
78
+ ## Opening a Pull Request
79
+
80
+ Pull requests are **welcome** for this repo!
81
+
82
+ Bugfixes will always be accepted, though in some cases some small changes may be requested.
83
+
84
+ However, if adding a feature or breaking change, please **open an issue first to discuss.** This ensures no time or work is wasted writing code that won’t be accepted to the project (see [Project Goals](https://openapi-ts.dev/openapi-fetch/about/#project-goals)). Undiscussed feature work may be rejected at the discretion of the maintainers.
85
+
86
+ ### Writing the commit
87
+
88
+ Create a new branch for your PR with `git checkout -b your-branch-name`. Add the relevant code as well as docs and tests. When you push everything up (`git push`), navigate back to your repo in GitHub and you should see a prompt to open a new PR.
89
+
90
+ While best practices for commit messages are encouraged (e.g. start with an imperative verb, keep it short, use the body if needed), this repo doesn’t follow any specific guidelines. Clarity is favored over strict rules. Changelogs are generated separately from git (see [the Changelogs section](#changelogs)).
91
+
92
+ ### Writing the PR notes
93
+
94
+ **Please fill out the template!** It’s a very lightweight template 🙂.
95
+
96
+ ### Adding docs
97
+
98
+ If you added a feature, or changed how something worked, please [update the docs](../../docs/)!
99
+
100
+ ### Passing CI
101
+
102
+ All PRs must fix lint errors, and all tests must pass. PRs will not be merged until all CI checks are “green” (✅).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Drew Powers
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,122 @@
1
+ <img src="../../docs/public/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />
2
+
3
+ openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **6 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.
4
+
5
+ | Library | Size (min) | “GET” request\* |
6
+ | :------------------------- | ---------: | :------------------------- |
7
+ | openapi-fetch | `6 kB` | `300k` ops/s (fastest) |
8
+ | openapi-typescript-fetch | `3 kB` | `300k` ops/s (fastest) |
9
+ | feature-fetch | `15 kB` | `300k` ops/s (fastest) |
10
+ | axios | `32 kB` | `225k` ops/s (1.3× slower) |
11
+ | superagent | `55 kB` | `50k` ops/s (6× slower) |
12
+ | openapi-typescript-codegen | `367 kB` | `100k` ops/s (3× slower) |
13
+
14
+ _\* [Benchmarks are approximate](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/test/index.bench.js) to just show rough baseline and will differ among machines and browsers. The relative performance between libraries is more reliable._
15
+
16
+ The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 6 kb package.
17
+
18
+ ```ts
19
+ import createClient from "openapi-fetch";
20
+ import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
21
+
22
+ const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
23
+
24
+ const {
25
+ data, // only present if 2XX response
26
+ error, // only present if 4XX or 5XX response
27
+ } = await client.GET("/blogposts/{post_id}", {
28
+ params: {
29
+ path: { post_id: "123" },
30
+ },
31
+ });
32
+
33
+ await client.PUT("/blogposts", {
34
+ body: {
35
+ title: "My New Post",
36
+ },
37
+ });
38
+ ```
39
+
40
+ `data` and `error` are typechecked and expose their shapes to Intellisense in VS Code (and any other IDE with TypeScript support). Likewise, the request `body` will also typecheck its fields, erring if any required params are missing, or if there’s a type mismatch.
41
+
42
+ `GET()`, `PUT()`, `POST()`, etc. are thin wrappers around the native [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) (which you can [swap for any call](https://openapi-ts.dev/openapi-fetch/api/#create-client)).
43
+
44
+ Notice there are no generics, and no manual typing. Your endpoint’s request and response were inferred automatically. This is a huge improvement in the type safety of your endpoints because **every manual assertion could lead to a bug**! This eliminates all of the following:
45
+
46
+ - ✅ No typos in URLs or params
47
+ - ✅ All parameters, request bodies, and responses are type-checked and 100% match your schema
48
+ - ✅ No manual typing of your API
49
+ - ✅ Eliminates `any` types that hide bugs
50
+ - ✅ Also eliminates `as` type overrides that can also hide bugs
51
+ - ✅ All of this in a **6 kb** client package 🎉
52
+
53
+ ## Setup
54
+
55
+ Install this library along with [openapi-typescript](../openapi-typescript):
56
+
57
+ ```bash
58
+ npm i openapi-fetch
59
+ npm i -D openapi-typescript typescript
60
+ ```
61
+
62
+ > **Highly recommended**
63
+ >
64
+ > Enable [noUncheckedIndexedAccess](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess) in your `tsconfig.json` ([docs](/advanced#enable-nouncheckedindexaccess-in-your-tsconfigjson))
65
+
66
+ Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:
67
+
68
+ ```bash
69
+ npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
70
+ ```
71
+
72
+ Lastly, be sure to **run typechecking** in your project. This can be done by adding `tsc --noEmit` to your [npm scripts](https://docs.npmjs.com/cli/v9/using-npm/scripts) like so:
73
+
74
+ ```json
75
+ {
76
+ "scripts": {
77
+ "test:ts": "tsc --noEmit"
78
+ }
79
+ }
80
+ ```
81
+
82
+ And run `npm run test:ts` in your CI to catch type errors.
83
+
84
+ > **TIP:**
85
+ >
86
+ > Use `tsc --noEmit` to check for type errors rather than relying on your linter or your build command. Nothing will typecheck as accurately as the TypeScript compiler itself.
87
+
88
+ ## Basic usage
89
+
90
+ The best part about using openapi-fetch over oldschool codegen is no documentation needed. openapi-fetch encourages using your existing OpenAPI documentation rather than trying to find what function to import, or what parameters that function wants:
91
+
92
+ ![OpenAPI schema example](../../docs/public/assets/openapi-schema.png)
93
+
94
+ ```ts
95
+ import createClient from "openapi-fetch";
96
+ import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
97
+
98
+ const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
99
+
100
+ const { data, error } = await client.GET("/blogposts/{post_id}", {
101
+ params: {
102
+ path: { post_id: "my-post" },
103
+ query: { version: 2 },
104
+ },
105
+ });
106
+
107
+ const { data, error } = await client.PUT("/blogposts", {
108
+ body: {
109
+ title: "New Post",
110
+ body: "<p>New post body</p>",
111
+ publish_date: new Date("2023-03-01T12:00:00Z").getTime(),
112
+ },
113
+ });
114
+ ```
115
+
116
+ 1. The HTTP method is pulled directly from `createClient()`
117
+ 2. You pass in your desired `path` to `GET()`, `PUT()`, etc.
118
+ 3. TypeScript takes over the rest and returns helpful errors for anything missing or invalid
119
+
120
+ ## 📓 Docs
121
+
122
+ [View Docs](https://openapi-ts.dev/openapi-fetch/)