fix(verify): harden sdk verification flow

Add a public Effect live layer and update docs/examples to use it.

Make the consumer live test hermetic, run live helpers against dist, tighten operation error matching, and move unit test coverage scripts to the warning-free Vitest path.

Author: altaywtf

AGENTS.md

@@ -19,8 +19,8 @@
 - `vp install`
 - `vp check .`
 - `vp pack`
-- `vp test run --passWithNoTests`
-- `vp test run --coverage --passWithNoTests`
+- `vp run test`
+- `vp run coverage`
 - `vp run test:live`
 - `vp run verify`
 - `vp run bootstrap:tokens`

README.md

@@ -71,7 +71,7 @@ const duration = secondsToReadableDuration(444);
 
 ```ts
 import { Effect } from "effect";
-import { createPutioSdkEffectClient, makePutioSdkLayer } from "@putdotio/sdk";
+import { createPutioSdkEffectClient, makePutioSdkLiveLayer } from "@putdotio/sdk";
 
 const sdk = createPutioSdkEffectClient();
 
@@ -80,17 +80,14 @@ const program = sdk.files
     per_page: 20,
     total: 1,
   })
-  .pipe(
-    Effect.provide(
-      makePutioSdkLayer({
-        accessToken: process.env.PUTIO_TOKEN!,
-      }),
-    ),
-  );
+  .pipe(Effect.provide(makePutioSdkLiveLayer({ accessToken: process.env.PUTIO_TOKEN! })));
 
 const result = await Effect.runPromise(program);
 ```
 
+`makePutioSdkLiveLayer(...)` provides both the SDK config and the default fetch-backed `HttpClient`.
+Use `makePutioSdkLayer(...)` only when you want to supply your own `HttpClient` service.
+
 ## Side-By-Side Usage
 
 Both client styles expose the same domain surface:
@@ -161,6 +158,7 @@ The package is designed around standard Web APIs. Host runtimes should provide:
 - `URL` and `URLSearchParams`
 - `AbortController`
 - `FormData`
+- `btoa` for username/password auth flows such as `auth.login(...)`
 
 For upload flows, the host should also provide file-compatible inputs such as `File` or `Blob`.
 
@@ -203,7 +201,7 @@ Effect consumers keep errors in the typed error channel instead of throwing:
 
 ```ts
 import { Effect } from "effect";
-import { createPutioSdkEffectClient, makePutioSdkLayer } from "@putdotio/sdk";
+import { createPutioSdkEffectClient, makePutioSdkLiveLayer } from "@putdotio/sdk";
 
 const sdk = createPutioSdkEffectClient();
 
@@ -220,11 +218,7 @@ const handled = sdk.files
 
       return Effect.fail(error);
     }),
-    Effect.provide(
-      makePutioSdkLayer({
-        accessToken: process.env.PUTIO_TOKEN!,
-      }),
-    ),
+    Effect.provide(makePutioSdkLiveLayer({ accessToken: process.env.PUTIO_TOKEN! })),
   );
 ```
 
@@ -269,10 +263,10 @@ The Effect client also works well when you want the canonical typed API:
 ```ts
 import { useQuery } from "@tanstack/react-query";
 import { Effect } from "effect";
-import { createPutioSdkEffectClient, makePutioSdkLayer } from "@putdotio/sdk";
+import { createPutioSdkEffectClient, makePutioSdkLiveLayer } from "@putdotio/sdk";
 
 const sdk = createPutioSdkEffectClient();
-const sdkLayer = makePutioSdkLayer({
+const sdkLayer = makePutioSdkLiveLayer({
   accessToken: token,
 });
 

docs/TESTING.md

@@ -22,6 +22,8 @@ The live verification layer lives in:
 - `test/live/domains/*.ts`
 - `test/live/support/*`
 
+Live tests execute the built SDK from `dist/**`, so direct live targets should always run after `vp pack`.
+
 ## Local Checks
 
 Default test runs intentionally exclude `test/live/**`.
@@ -32,8 +34,8 @@ Run:
 vp install
 vp check .
 vp pack
-vp test run --passWithNoTests
-vp test run --coverage --passWithNoTests
+vp run test
+vp run coverage
 ```
 
 The local suite focuses on the shared runtime in `src/core`.
@@ -61,31 +63,37 @@ Example env file:
 
 - `.env.example`
 
-Expected variables:
+Bootstrap-first variables:
 
-- `PUTIO_TOKEN_FIRST_PARTY`
-- `PUTIO_TOKEN_THIRD_PARTY`
-- `PUTIO_CLIENT_ID`
+- `PUTIO_TEST_USERNAME`
+- `PUTIO_TEST_PASSWORD`
 - `PUTIO_CLIENT_ID_FIRST_PARTY`
 - `PUTIO_CLIENT_SECRET_FIRST_PARTY`
 
 Optional credential-fixture variables:
 
-- `PUTIO_TEST_USERNAME`
-- `PUTIO_TEST_PASSWORD`
 - `PUTIO_TEST_TOTP_REFERENCE`
 - `PUTIO_TEST_TOTP`
 - `PUTIO_TEST_SECONDARY_USERNAME`
 - `PUTIO_TEST_SECONDARY_PASSWORD`
 - `PUTIO_TEST_SECONDARY_TOTP_REFERENCE`
 - `PUTIO_TEST_SECONDARY_TOTP`
+- `PUTIO_CLIENT_ID_THIRD_PARTY`
 - `PUTIO_1PASSWORD_RUNTIME_ITEM_ID`
 
-If the explicit token vars are missing, the live harness can still hydrate them from:
+Optional direct runtime variables:
+
+- `PUTIO_TOKEN_FIRST_PARTY`
+- `PUTIO_TOKEN_THIRD_PARTY`
+- `PUTIO_CLIENT_ID`
+
+If direct token vars are missing, the live harness can still hydrate them from:
 
 1. legacy local aliases
 2. a runtime-token 1Password item when `OP_SERVICE_ACCOUNT_TOKEN` and `PUTIO_1PASSWORD_RUNTIME_ITEM_ID` are set
 
+See `.env.example` for the current bootstrap-oriented layout and supported optional aliases.
+
 Never print token values in command output, docs, comments, or commits.
 
 ## Live Commands
@@ -113,8 +121,8 @@ Run a credentialed live target with 1Password:
 
 ```bash
 export OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_PUTIO_FRONTEND_CI"
-op run --env-file=.env.example -- \
-  vp pack && vp test run --config vitest.live.config.ts test/live/auth-credentials.test.ts
+op run --env-file=.env.example -- sh -lc \
+  'vp pack && vp test run --config vitest.live.config.ts test/live/auth-credentials.test.ts'
 ```
 
 ## Consumer Verification

package.json

@@ -36,23 +36,23 @@
     "build": "vp pack",
     "check": "vp check .",
     "clean": "rm -rf .live-build .turbo coverage dist",
-    "coverage": "vp test run --coverage --passWithNoTests",
+    "coverage": "vitest run --coverage --passWithNoTests",
     "dev": "vp pack --watch",
     "prepack": "vp pack",
-    "test": "vp test run --passWithNoTests",
+    "test": "vitest run --passWithNoTests",
     "test:live": "vp pack && vp test run --config vitest.live.config.ts",
-    "verify": "vp check . && vp pack && vp test run --passWithNoTests && vp test run --coverage --passWithNoTests"
+    "verify": "vp check . && vp pack && vitest run --passWithNoTests && vitest run --coverage --passWithNoTests"
   },
   "dependencies": {
     "@effect/platform": "0.94.5",
     "effect": "3.19.19"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/coverage-v8": "4.1.0",
     "typescript": "^5.9.3",
     "vite-plus": "^0.1.11",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+    "vitest": "4.1.0"
   },
   "engines": {
     "node": ">=24.14.0 <25"