fix(claim): send canonical token wire field + surface session_token (#15)

Two user-impacting bugs in Client.Claim:

1. Wire-name drift. The SDK was posting body["jwt"] = opts.JWT — the
   deprecated alias. The api ClaimRequest doc explicitly names sdk-go as
   one of three drift sources for the legacy `jwt` field (with dashboard
   + MCP). Server accepts both with `token` winning on collision, so this
   is wire-compatible.

2. ClaimResult.SessionToken missing. The api /claim handler returns a
   freshly minted 24h session JWT in the response body, but the SDK's
   result struct contained no field for it — every caller that wanted
   to provision resources right after Claim() had to run a separate
   magic-link login round-trip.

Changes:
- ClaimResult gains SessionToken `json:"session_token,omitempty"`.
- ClaimOpts gains canonical Token field (json:"token"); existing JWT
  field retained as deprecated alias (json:"-") with claimToken() helper
  that mirrors api.ClaimRequest.claimToken precedence (Token wins).
- claim.go sends body["token"] = opts.claimToken(); validation message
  updated from "JWT is required" → "Token is required".
- Tests: TestClaim asserts wire body contains no `jwt` and has `token`,
  plus SessionToken round-trip. Two regression tests added —
  TestClaim_JWTFieldBackwardCompat (deprecated field still compiles and
  the SDK still translates to canonical wire) and TestClaim_TokenWinsOverJWT
  (precedence rule mirrors api).

Existing callers compile unchanged (JWT field retained). Project
coverage 97.8% (>95% floor), patch coverage 100%.

Author: mastermanas805

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to the Go SDK for instanode.dev are documented here.
 The SDK follows semver: minor bumps add new API surface, major bumps break
 existing callers.
 
+## Unreleased
+
+### Fixed
+
+- **`Client.Claim` now sends the canonical `token` wire field instead of the
+  deprecated `jwt` alias.** The api ClaimRequest doc names the Go SDK as one
+  of three drift sources for the legacy `jwt` name (alongside the dashboard
+  and MCP). The server still accepts both, so this is wire-compatible, but
+  closes the drift.
+
+### Added
+
+- **`ClaimResult.SessionToken`** (`string`, `json:"session_token,omitempty"`).
+  Populated when the api mints a session JWT for the newly created team on
+  `POST /claim`. Callers can use it as the Bearer token for follow-up
+  authenticated requests with no separate login round-trip. 24h TTL.
+- **`ClaimOpts.Token`** (`string`, `json:"token,omitempty"`) — canonical
+  onboarding-token field, mirrors api `ClaimRequest.Token`. The existing
+  `ClaimOpts.JWT` field is retained as a deprecated fallback (no JSON tag —
+  read-only by the SDK on the client side); new callers should use `Token`.
+  When both are set, `Token` wins.
+
 ## v0.3.0 — 2026-05-20 (BugBash B17)
 
 ### Fixed

instant/claim.go

@@ -7,22 +7,29 @@ import (
 
 // Claim converts an anonymous session into a registered team account.
 //
-// The JWT is the onboarding token obtained from the upgrade URL. When
+// The Token is the onboarding token obtained from the upgrade URL. When
 // instanode.dev provisions an anonymous resource it returns a Note field
-// containing a URL like https://instanode.dev/start?t=<jwt>. Extract the
+// containing a URL like https://instanode.dev/start?t=<token>. Extract the
 // "t" query parameter and pass it here.
 //
-// Claim is one-time: anonymous (24h TTL) resources associated with the JWT's
-// fingerprint are transferred to the new team and given a permanent (no-expiry)
-// lifetime on the free tier. No trial period is started — paid tiers (hobby,
-// pro, team) require a separate Razorpay checkout from the dashboard.
+// Claim is one-time: anonymous (24h TTL) resources associated with the
+// token's fingerprint are transferred to the new team and given a permanent
+// (no-expiry) lifetime on the free tier. No trial period is started — paid
+// tiers (hobby, pro, team) require a separate Razorpay checkout from the
+// dashboard.
 //
-// Returns [*APIError] with StatusCode 409 if the JWT has already been claimed.
+// On success the returned [ClaimResult.SessionToken] holds a freshly minted
+// 24h session JWT for the new team — callers can pass it as the Bearer
+// token on follow-up authenticated requests without a separate login round
+// trip.
+//
+// Returns [*APIError] with StatusCode 409 if the token has already been
+// claimed.
 //
 // Example:
 //
 //	result, err := client.Claim(ctx, instant.ClaimOpts{
-//	    JWT:      upgradeToken,  // from "t" query param of the upgrade URL
+//	    Token:    upgradeToken,  // from "t" query param of the upgrade URL
 //	    Email:    "dev@example.com",
 //	    TeamName: "Acme Corp",   // optional; defaults to email
 //	})
@@ -31,17 +38,22 @@ import (
 //	    return
 //	}
 //	if err != nil { log.Fatal(err) }
-//	fmt.Println("team_id:", result.TeamID)
+//	fmt.Println("team_id:", result.TeamID, "session:", result.SessionToken)
 func (c *Client) Claim(ctx context.Context, opts ClaimOpts) (*ClaimResult, error) {
-	if opts.JWT == "" {
-		return nil, fmt.Errorf("Claim: JWT is required")
+	token := opts.claimToken()
+	if token == "" {
+		return nil, fmt.Errorf("Claim: Token is required")
 	}
 	if opts.Email == "" {
 		return nil, fmt.Errorf("Claim: Email is required")
 	}
 
+	// Canonical wire field is `token` (api ClaimRequest, 2026-05-20). The
+	// legacy `jwt` alias is still server-accepted but documented as
+	// deprecated — SDKs are one of the named drift sources, so we send the
+	// canonical name only.
 	body := map[string]string{
-		"jwt":   opts.JWT,
+		"token": token,
 		"email": opts.Email,
 	}
 	if opts.TeamName != "" {

instant/client_test.go

@@ -542,30 +542,92 @@ func TestAbsoluteURL(t *testing.T) {
 func TestClaim(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		body := decodeJSONBody(t, r.Body)
-		if body["jwt"] != "ey.j.j" || body["email"] != "a@b.c" || body["team_name"] != "Acme" {
+		// Canonical wire field is `token` (api ClaimRequest, 2026-05-20).
+		// The SDK must never send the deprecated `jwt` alias even when the
+		// caller supplied the deprecated [ClaimOpts.JWT] field.
+		if _, hasJWT := body["jwt"]; hasJWT {
+			t.Errorf("body must not contain deprecated `jwt` field; got %+v", body)
+		}
+		if body["token"] != "ey.j.j" || body["email"] != "a@b.c" || body["team_name"] != "Acme" {
 			t.Errorf("body = %+v", body)
 		}
 		_ = json.NewEncoder(w).Encode(map[string]any{
-			"ok": true, "team_id": "T", "user_id": "U", "message": "ok",
+			"ok":            true,
+			"team_id":       "T",
+			"user_id":       "U",
+			"session_token": "sess.jwt.tok",
+			"message":       "ok",
 		})
 	}))
 	defer srv.Close()
 	c := New(WithBaseURL(srv.URL))
-	r, err := c.Claim(context.Background(), ClaimOpts{JWT: "ey.j.j", Email: "a@b.c", TeamName: "Acme"})
+	r, err := c.Claim(context.Background(), ClaimOpts{Token: "ey.j.j", Email: "a@b.c", TeamName: "Acme"})
 	if err != nil {
 		t.Fatalf("Claim: %v", err)
 	}
 	if r.TeamID != "T" {
 		t.Errorf("TeamID = %q", r.TeamID)
 	}
+	if r.SessionToken != "sess.jwt.tok" {
+		t.Errorf("SessionToken = %q, want sess.jwt.tok", r.SessionToken)
+	}
 	if _, err := c.Claim(context.Background(), ClaimOpts{Email: "x"}); err == nil {
-		t.Error("missing JWT should error")
+		t.Error("missing Token should error")
 	}
-	if _, err := c.Claim(context.Background(), ClaimOpts{JWT: "x"}); err == nil {
+	if _, err := c.Claim(context.Background(), ClaimOpts{Token: "x"}); err == nil {
 		t.Error("missing Email should error")
 	}
 }
 
+// TestClaim_JWTFieldBackwardCompat — the deprecated [ClaimOpts.JWT] field is
+// still accepted as a fallback so existing call sites compile unchanged, but
+// the wire body must still send the canonical `token` field.
+func TestClaim_JWTFieldBackwardCompat(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body := decodeJSONBody(t, r.Body)
+		if _, hasJWT := body["jwt"]; hasJWT {
+			t.Errorf("body must not contain deprecated `jwt` field; got %+v", body)
+		}
+		if body["token"] != "legacy.jwt.val" {
+			t.Errorf("token field = %v, want legacy.jwt.val", body["token"])
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"ok": true, "team_id": "T", "user_id": "U", "message": "ok",
+		})
+	}))
+	defer srv.Close()
+	c := New(WithBaseURL(srv.URL))
+	// Caller supplies legacy JWT field; SDK must translate to canonical wire.
+	_, err := c.Claim(context.Background(), ClaimOpts{JWT: "legacy.jwt.val", Email: "a@b.c"})
+	if err != nil {
+		t.Fatalf("Claim: %v", err)
+	}
+}
+
+// TestClaim_TokenWinsOverJWT — when both fields are set, the canonical
+// Token field takes precedence (mirrors api ClaimRequest.claimToken).
+func TestClaim_TokenWinsOverJWT(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body := decodeJSONBody(t, r.Body)
+		if body["token"] != "canonical.tok" {
+			t.Errorf("token = %v, want canonical.tok (Token must win over JWT)", body["token"])
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"ok": true, "team_id": "T", "user_id": "U", "message": "ok",
+		})
+	}))
+	defer srv.Close()
+	c := New(WithBaseURL(srv.URL))
+	_, err := c.Claim(context.Background(), ClaimOpts{
+		Token: "canonical.tok",
+		JWT:   "deprecated.tok",
+		Email: "a@b.c",
+	})
+	if err != nil {
+		t.Fatalf("Claim: %v", err)
+	}
+}
+
 func TestClaimTokens(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer sk-1" {

instant/example_test.go

@@ -79,7 +79,7 @@ func ExampleClient_Claim() {
 	client := instant.New(instant.WithBaseURL("http://localhost:30080"))
 
 	result, err := client.Claim(ctx, instant.ClaimOpts{
-		JWT:      "eyJhbGci...", // from ?t= query param on the upgrade URL
+		Token:    "eyJhbGci...", // from ?t= query param on the upgrade URL
 		Email:    "dev@example.com",
 		TeamName: "Acme Corp",
 	})

instant/types.go

@@ -154,6 +154,15 @@ type ClaimResult struct {
 	// UserID is the UUID of the newly created user.
 	UserID string `json:"user_id"`
 
+	// SessionToken is a freshly minted session JWT for the newly created
+	// team, suitable for immediate use as the bearer token on follow-up
+	// authenticated requests. Empty when the server elected not to mint one
+	// (e.g. the [Client.ClaimTokens] path that supplies its own API key).
+	//
+	// 24h TTL; re-login on expiry (the API exposes no refresh endpoint).
+	// Treat as a secret.
+	SessionToken string `json:"session_token,omitempty"`
+
 	// Message is a human-readable confirmation message.
 	Message string `json:"message"`
 }
@@ -195,9 +204,24 @@ type ProvisionOpts struct {
 }
 
 // ClaimOpts are the parameters for the Claim method.
+//
+// Field-name policy (matches api ClaimRequest, 2026-05-20): Token is the
+// canonical onboarding-token field. JWT is the deprecated alias kept so
+// existing callers compile unchanged — when both are set, Token wins. New
+// code should set Token only. The SDK now sends the canonical `token` wire
+// field on every request, closing the three-name drift (jwt / token /
+// INSTANODE_TOKEN) the api ClaimRequest doc explicitly flags.
 type ClaimOpts struct {
-	// JWT is the onboarding token obtained from the upgrade URL query parameter (required).
-	JWT string `json:"jwt"`
+	// Token is the canonical onboarding token obtained from the upgrade URL
+	// query parameter "t" (required when JWT is unset).
+	Token string `json:"token,omitempty"`
+
+	// JWT is the deprecated alias for Token. Provided for backward
+	// compatibility with existing code; new callers should use Token.
+	// When both are set, Token wins.
+	//
+	// Deprecated: use Token.
+	JWT string `json:"-"`
 
 	// Email is the user's email address (required).
 	Email string `json:"email"`
@@ -206,6 +230,17 @@ type ClaimOpts struct {
 	TeamName string `json:"team_name,omitempty"`
 }
 
+// claimToken returns the canonical onboarding token from a ClaimOpts,
+// preferring the new Token field and falling back to the deprecated JWT
+// field. Centralised so every read site agrees on the precedence (mirrors
+// api/internal/handlers/onboarding.go: ClaimRequest.claimToken).
+func (o ClaimOpts) claimToken() string {
+	if o.Token != "" {
+		return o.Token
+	}
+	return o.JWT
+}
+
 // APIError is returned when the server responds with a 4xx or 5xx status code.
 // It implements the error interface so it can be used directly in error comparisons.
 type APIError struct {

instant_test.go

@@ -463,10 +463,11 @@ func TestClaim_Success(t *testing.T) {
 		}
 		var body map[string]string
 		json.NewDecoder(r.Body).Decode(&body) //nolint:errcheck
-		if body["jwt"] == "" || body["email"] == "" {
+		// Canonical wire field is `token` (api ClaimRequest, 2026-05-20).
+		if body["token"] == "" || body["email"] == "" {
 			writeJSON(w, http.StatusBadRequest, map[string]any{
-				"error":   "missing_fields",
-				"message": "jwt and email are required",
+				"error":   "missing_token",
+				"message": "token and email are required",
 			})
 			return
 		}
@@ -480,7 +481,7 @@ func TestClaim_Success(t *testing.T) {
 
 	client := serve(t, mux)
 	result, err := client.Claim(context.Background(), instant.ClaimOpts{
-		JWT:      "test-jwt",
+		Token:    "test-jwt",
 		Email:    "dev@example.com",
 		TeamName: "Test Corp",
 	})