@goable-io/sdk 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Carucci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,22 @@
 # @goable-io/sdk
 
+[![npm](https://img.shields.io/npm/v/@goable-io/sdk.svg)](https://www.npmjs.com/package/@goable-io/sdk)
+[![CI](https://github.com/goable-io/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/goable-io/sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
 TypeScript client for the [Goable](https://goable.io) API — 0-100 suitability
 scoring for outdoor activities (water, snow, air, land) from real-time weather
 and multi-domain physics.
 
-> **Status: v0.1, publish-ready (not yet on npm).** Thin, typed transport over
-> the public tenant-facing REST surface. Zero runtime dependencies. Works in
-> Node ≥18 and modern browser/edge runtimes (uses the global `fetch`).
+Thin, typed transport over the public tenant-facing REST surface. **Zero runtime
+dependencies.** Works in Node ≥18 and modern browser/edge runtimes (uses the
+global `fetch`). Published to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements).
 
 ## Install
 
 ```bash
-npm install @goable-io/sdk   # once published
+npm install @goable-io/sdk
+# or: pnpm add @goable-io/sdk
 ```
 
 ## Quickstart
@@ -21,6 +26,7 @@ import { GoableClient } from "@goable-io/sdk"
 
 const goable = new GoableClient({ apiKey: process.env.GOABLE_API_KEY! })
 
+// Score a single activity at a location + time window
 const result = await goable.score({
   activity: "kitesurfing",
   location: { lat: 43.7, lng: 7.27 },
@@ -32,14 +38,44 @@ result.verdict  // "unsafe" | "poor" | "marginal" | "fair" | "favorable" | "exce
 result.confidence
 ```
 
+Inverse query — "where should I go?" — ranks sub-spots for an activity within
+a region:
+
+```ts
+const spots = await goable.recommendSpot({
+  activity: "kitesurfing",
+  region: { center: { lat: 43.7, lng: 7.27 }, radiusKm: 50 },
+  window: { from: "2026-06-01T06:00:00Z", to: "2026-06-01T18:00:00Z" },
+  topK: 5,
+})
+```
+
+## Authentication
+
+Every request carries your tenant API key. The canonical production header is
+**`X-Goable-Key`**, which the client sends automatically:
+
+```ts
+new GoableClient({ apiKey: "gk_…" })   // → sends "X-Goable-Key: gk_…"
+```
+
+> The API also accepts `Authorization: Bearer <key>` as a legacy fallback for
+> direct testing, but new integrations should use the default `X-Goable-Key`
+> path. (Production traffic sits behind CloudFront, which reserves the
+> `Authorization` header for its own signature — the custom header sidesteps
+> that.)
+
+Mint a key from the tenant portal at
+[console.goable.io/portal/keys](https://console.goable.io/portal/keys).
+
 ## Configuration
 
 ```ts
 new GoableClient({
-  apiKey: "…",                    // required — sent as Authorization: Bearer
+  apiKey: "…",                      // required — sent as X-Goable-Key
   baseUrl: "https://api.goable.io", // default
-  timeoutMs: 30_000,               // default; 0 disables
-  fetch: customFetch,              // default globalThis.fetch (inject for Node <18 / tests)
+  timeoutMs: 30_000,                // default; 0 disables
+  fetch: customFetch,               // default globalThis.fetch (inject for Node <18 / tests)
 })
 ```
 
@@ -53,6 +89,7 @@ new GoableClient({
 | `scoreHistorical(input)` | `POST /v1/score/historical` | climatology percentiles (Pro+) |
 | `scorePortfolio(input)` | `POST /v1/score/portfolio` | multi-spot joint variance |
 | `explainCounterfactual(input)` | `POST /v1/score/explain-counterfactual` | binding constraint, sensitivities, best window/spot |
+| `recommendSpot(input)` | `POST /v1/recommend-spot` | inverse query: top-K ranked sub-spots |
 | `decision(input)` | `POST /v1/decision` | personalized go/no-go (Pro+) |
 | `deleteUserData(pseudonym)` | `DELETE /v1/decision/user-data/:p` | GDPR erasure; returns receipt headers |
 | `explain(input)` / `briefing(input)` | `POST /v1/intelligence/*` | LLM narratives (Pro+) |
@@ -60,6 +97,8 @@ new GoableClient({
 | `quote(input)` | `POST /v1/underwriting/quote` | parametric premium (Scale) |
 | `health()` | `GET /v1/health` | liveness |
 
+Full endpoint reference: [goable.io/docs](https://goable.io/docs).
+
 ## Errors
 
 ```ts
@@ -69,8 +108,8 @@ try {
   await goable.score({ activity: "kitesurfing", location: { lat: 43.7, lng: 7.27 }, ensemble: true })
 } catch (err) {
   if (err instanceof GoableApiError) {
-    err.status  // 402
-    err.code    // "PAYMENT_REQUIRED"
+    err.status  // e.g. 402
+    err.code    // e.g. "PAYMENT_REQUIRED"
     err.issues  // Zod issues on 422 VALIDATION_ERROR
     err.detail  // free-form context (e.g. plan info)
   } else if (err instanceof GoableNetworkError) {
@@ -82,40 +121,23 @@ try {
 ## Browser use
 
 The client runs in the browser, but **API keys are secrets** — prefer
-server-side use. For direct browser calls the API's CORS allowlist must
-include your origin (contact Goable to allowlist it).
+server-side use. For direct browser calls the API's CORS allowlist must include
+your origin (contact Goable to allowlist it).
 
 ## Types are generated from the API contract
 
-The request/response types are **generated** from the API's OpenAPI
-document (`apps/api/src/openapi/spec.ts`) via
-[`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) —
-they are never hand-authored, so they can't drift from the server. When the
-API contract changes, a maintainer runs:
-
-```bash
-pnpm --filter @goable-io/sdk gen
-```
-
-which rewrites `src/generated/api.ts` + `openapi.json`. A test
-(`generatedFresh.test.ts`) fails in CI if the committed output is stale, so
-the types are always in lock-step with the contract. Adding a brand-new
-endpoint is the only manual step (a new client method).
+The request/response types are **generated** from the Goable API's OpenAPI
+document (`openapi.json`) via
+[`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) — they
+are never hand-authored, so they can't drift from the contract. The committed
+`openapi.json` tracks the live public API; see
+[CONTRIBUTING.md](./CONTRIBUTING.md) for how it stays in sync.
 
-Request types are precise (the API rejects unknown fields). Some response
-bodies are modelled as open objects where the endpoint returns a rich,
-documented payload — the full wire payload is always returned, and these
-tighten automatically as the OpenAPI response schemas are enriched.
+## Contributing & releases
 
-## Release (maintainers)
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Releases are automated: merging to
+`main` publishes to npm with provenance.
 
-Publishing is automated by `.github/workflows/sdk-release.yml` (on changes
-to `packages/sdk/**` on `main`): it builds, runs the freshness guard +
-tests, resolves the next version, prints `npm pack --dry-run` as a leak
-check, and `pnpm publish --access public` using the org `NPM_TOKEN`. The
-private engine never leaves the repo — only this package's `files` are
-published. `publishConfig` repoints `main`/`types`/`exports` at `dist/` at
-publish time, so in-repo development keeps using the TS sources.
+## License
 
-> No npm provenance: it requires a public source repo, and the SDK source
-> stays in this private monorepo by design.
+MIT © Fabio Carucci

package/dist/generated/api.d.ts

@@ -1,7 +1,7 @@
 /**
  * GENERATED FILE — do not edit by hand.
- * Source: apps/api/src/openapi/spec.ts (buildOpenApiSpec).
- * Regenerate: pnpm --filter @goable-io/sdk gen
+ * Source: openapi.json (the committed Goable API contract).
+ * Regenerate: pnpm gen
  */
 export interface paths {
     "/v1/health": {

package/dist/generated/api.js

@@ -1,7 +1,7 @@
 /**
  * GENERATED FILE — do not edit by hand.
- * Source: apps/api/src/openapi/spec.ts (buildOpenApiSpec).
- * Regenerate: pnpm --filter @goable-io/sdk gen
+ * Source: openapi.json (the committed Goable API contract).
+ * Regenerate: pnpm gen
  */
 export {};
 //# sourceMappingURL=api.js.map

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@goable-io/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript client for the Goable API — suitability scoring for outdoor activities.",
   "private": false,
   "type": "module",
   "license": "MIT",
-  "homepage": "https://goable.io",
+  "author": "Fabio Carucci <contact@fabio-carucci.com>",
+  "homepage": "https://github.com/goable-io/sdk#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/goable-io/goable",
-    "directory": "packages/sdk"
+    "url": "git+https://github.com/goable-io/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/goable-io/sdk/issues"
   },
   "keywords": [
     "goable",
@@ -30,28 +33,28 @@
       "default": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "src",
-    "README.md"
-  ],
+  "files": ["dist", "src", "README.md", "LICENSE"],
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "pnpm@11.3.0",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "gen": "tsx scripts/gen.ts",
+    "prepublishOnly": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
-  },
-  "scripts": {
-    "build": "tsc -b",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests",
-    "gen": "tsx scripts/gen.ts",
-    "clean": "rm -rf dist .turbo *.tsbuildinfo"
   }
-}
+}

package/src/generated/api.ts

@@ -1,7 +1,7 @@
 /**
  * GENERATED FILE — do not edit by hand.
- * Source: apps/api/src/openapi/spec.ts (buildOpenApiSpec).
- * Regenerate: pnpm --filter @goable-io/sdk gen
+ * Source: openapi.json (the committed Goable API contract).
+ * Regenerate: pnpm gen
  */
 
 export interface paths {