@theholocron/turbo-client 0.0.0-stage → 1.58.0-alpha.32

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Newton Koumantzelis
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.
package/README.md CHANGED
@@ -1,3 +1,22 @@
1
- # Temporary Holding Version
1
+ # `@theholocron/turbo-client`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript client for [Turborepo's Remote Cache](https://turborepo.com/docs/core-concepts/remote-caching), which Vercel
4
+ serves. The token is a Vercel token (what Turborepo reads as `TURBO_TOKEN`).
5
+
6
+ ## Install
7
+
8
+ ```bash
9
+ pnpm add @theholocron/turbo-client
10
+ ```
11
+
12
+ ## Usage
13
+
14
+ ```ts
15
+ import { createTurboClient } from "@theholocron/turbo-client";
16
+
17
+ const turbo = createTurboClient({ token: process.env.TURBO_TOKEN! });
18
+
19
+ // Is Remote Caching on for the team (`TURBO_TEAM`, a slug; a `team_...` id also works)?
20
+ const { status, readOnly } = await turbo.cache.status("acme");
21
+ // status: "enabled" | "disabled" | "over_limit" | "paused"; readOnly: the token can read but not upload
22
+ ```
@@ -0,0 +1,38 @@
1
+ import "@theholocron/http-client";
2
+ import { ErrorSink, Logger } from "@theholocron/observability/core";
3
+ /** Options for `createTurboClient()` and `createTurboRestClient()`. */
4
+ interface TurboClientOptions {
5
+ /** The token Turborepo sends to the remote cache: a Vercel token (`TURBO_TOKEN`). */
6
+ token: string;
7
+ /** Override base URL for testing. Defaults to https://api.vercel.com, which serves Turborepo's Remote Cache. */
8
+ baseUrl?: string;
9
+ /** Override fetch for testing. Defaults to globalThis.fetch. */
10
+ fetch?: typeof fetch;
11
+ /** Structured logger for request/response diagnostics. Defaults to a no-op. */
12
+ logger?: Logger;
13
+ /** Reports transport failures and unexpected 5xx. Defaults to a no-op. */
14
+ errors?: ErrorSink;
15
+ }
16
+ /** The states Vercel documents for Remote Caching: usable (`enabled`) or not, and why. */
17
+ type TurboCacheState = "enabled" | "disabled" | "over_limit" | "paused";
18
+ /** The response of `cache.status()`. `status` is typed loosely because the API may add states. */
19
+ interface TurboCacheStatus {
20
+ /** Whether Remote Caching is on for the team: one of {@link TurboCacheState}, or a state added later. */
21
+ status: TurboCacheState | (string & {});
22
+ /** Present and `true` when the token can read artifacts but cannot upload them. */
23
+ readOnly?: boolean;
24
+ }
25
+ /**
26
+ * How a team is named: Turborepo's `TURBO_TEAM` is a team slug (`acme`); a Vercel team id (`team_...`) is also
27
+ * accepted and sent as `teamId`.
28
+ */
29
+ export declare function teamQuery(team: string): Record<string, string>;
30
+ /** Creates a client for Turborepo's Remote Cache (served by Vercel) with a `cache` group, sharing one REST client. */
31
+ export declare function createTurboClient(opts: TurboClientOptions): {
32
+ cache: {
33
+ status: (team: string) => Promise<TurboCacheStatus>;
34
+ };
35
+ };
36
+ /** The client `createTurboClient()` returns. */
37
+ export type TurboClient = ReturnType<typeof createTurboClient>;
38
+ export type { TurboCacheState, TurboCacheStatus, TurboClientOptions };
package/dist/index.mjs ADDED
@@ -0,0 +1,31 @@
1
+ import { createRestClient } from "@theholocron/http-client";
2
+ // src/cache/cache.ts
3
+ /**
4
+ * How a team is named: Turborepo's `TURBO_TEAM` is a team slug (`acme`); a Vercel team id (`team_...`) is also
5
+ * accepted and sent as `teamId`.
6
+ */
7
+ function teamQuery(team) {
8
+ return team.startsWith("team_") ? { teamId: team } : { slug: team };
9
+ }
10
+ function cache(rest) {
11
+ return {
12
+ /** `GET /v8/artifacts/status` for the team: whether Remote Caching is enabled, and whether the token is read-only. */
13
+ status: (team) => rest.request("/v8/artifacts/status", { query: teamQuery(team) }) };
14
+ }
15
+ // src/utils.ts
16
+ function createTurboRestClient(opts) {
17
+ return createRestClient({
18
+ baseUrl: opts.baseUrl ?? "https://api.vercel.com",
19
+ token: opts.token,
20
+ vendor: "Turbo",
21
+ fetch: opts.fetch,
22
+ logger: opts.logger,
23
+ errors: opts.errors
24
+ });
25
+ }
26
+ // src/index.ts
27
+ /** Creates a client for Turborepo's Remote Cache (served by Vercel) with a `cache` group, sharing one REST client. */
28
+ function createTurboClient(opts) {
29
+ return { cache: cache(createTurboRestClient(opts)) };
30
+ }
31
+ export { createTurboClient, teamQuery };
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "@theholocron/turbo-client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.58.0-alpha.32",
4
+ "description": "A TypeScript client for Turborepo's Remote Cache API (served by Vercel)",
5
+ "keywords": [
6
+ "turbo",
7
+ "turborepo",
8
+ "remote-cache",
9
+ "typescript",
10
+ "http-client",
11
+ "api"
12
+ ],
13
+ "homepage": "https://docs.theholocron.dev/holocron/clients/turbo/",
14
+ "bugs": "https://github.com/theholocron/holocron/issues",
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/theholocron/holocron.git",
18
+ "directory": "clients/turbo-client"
19
+ },
20
+ "license": "MIT",
21
+ "author": "Newton Koumantzelis",
22
+ "sideEffects": false,
23
+ "type": "module",
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.mts",
27
+ "import": "./dist/index.mjs",
28
+ "default": "./dist/index.mjs"
29
+ }
30
+ },
31
+ "files": [
32
+ "dist"
33
+ ],
34
+ "dependencies": {
35
+ "@theholocron/http-client": "^1.58.0-alpha.32",
36
+ "@theholocron/observability": "^0.7.0-alpha.4"
37
+ },
38
+ "devDependencies": {
39
+ "@types/node": "^26",
40
+ "@vitest/coverage-v8": "^5.1.0",
41
+ "@vitest/eslint-plugin": "^1.6.28",
42
+ "eslint": "^10.14.0",
43
+ "eslint-plugin-n": "^18.5.0",
44
+ "globals": "^17.14.0",
45
+ "tsdown": "^0.23.5",
46
+ "typescript": "^5.9.3",
47
+ "vitest": "^5.1.0",
48
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
49
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17",
50
+ "@theholocron/tsconfig": "^8.9.0-alpha.17",
51
+ "@theholocron/vitest-config": "^8.9.0-alpha.17"
52
+ },
53
+ "engines": {
54
+ "node": ">=22.0.0"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "scripts": {
60
+ "build": "tsdown && node ../scripts/check-bundle-size.mjs",
61
+ "lint:code": "eslint .",
62
+ "test:unit": "vitest run --coverage",
63
+ "test:watch": "vitest",
64
+ "typecheck": "tsc --noEmit"
65
+ }
6
66
  }