happyskills 1.12.0 → 1.12.1

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.12.1] - 2026-06-23
+
+### Changed
+- On a rate-limit `429`, steer anonymous callers to sign in instead of just retrying. When the API flags an anonymous trip on the search/resolve paths (`error.details.login_helps`), the CLI prints "You've hit the anonymous rate limit. Sign in or create a free account for a much higher limit — run `happyskills login`" (rather than a bare "wait and retry"), and `--json` mode emits a `login` `next_step`. Authenticated and `/auth/*` trips are unchanged. (Pairs with API `api-v5.15.3`.)
+
 ## [1.12.0] - 2026-06-22
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.12.0",
+	"version": "1.12.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/api/client.js

@@ -100,12 +100,22 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 
 		if (res.status === 429) {
 			const retry_after = res.headers.get('retry-after')
-			const retry_msg = retry_after
-				? `API rate limit reached. Please wait ${retry_after} seconds and try again.`
-				: 'API rate limit reached. Please wait and try again.'
+			// The API sets login_helps when the caller is anonymous on a path where
+			// signing in lifts the cap (search/resolve) — turn the dead-end into a
+			// sign-up nudge instead of a bare "wait and retry".
+			const login_helps = !!(err_details && err_details.login_helps)
+			const wait_hint = retry_after ? ` (or wait ${retry_after}s and retry)` : ''
+			const retry_msg = login_helps
+				? `You've hit the anonymous rate limit. Sign in or create a free account for a much higher limit — run \`happyskills login\`${wait_hint}.`
+				: (retry_after
+					? `API rate limit reached. Please wait ${retry_after} seconds and try again.`
+					: 'API rate limit reached. Please wait and try again.')
 			const err = new ApiError(retry_msg, 429, 'RATE_LIMITED')
 			err.retry_after = retry_after ? parseInt(retry_after) : null
 			if (err_details) err.details = { ...err.details, ...err_details }
+			// The JSON-mode marshaller builds next_step from err.context (not details),
+			// so stash the branch inputs there to get the LOGIN vs RETRY next_step.
+			err.context = { login_helps, ...(retry_after ? { retry_after_seconds: parseInt(retry_after) } : {}) }
 			throw err
 		}
 

package/src/constants/next_step_by_error_code.js

@@ -74,11 +74,24 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'A network error interrupted the request. Retry shortly.',
 		{ retry_after_seconds: 5, max_attempts: 3 }
 	),
-	RATE_LIMITED: (msg, ctx = {}) => recovery(
-		RETRY,
-		'Rate limit reached. Retry after the suggested interval.',
-		{ retry_after_seconds: ctx.retry_after_seconds || 30, max_attempts: 3 }
-	),
+	// An anonymous caller throttled on a per-IP bucket gets a much higher cap (and
+	// their own per-user budget) once signed in, so when the API flags `login_helps`
+	// we steer them to authenticate instead of just retrying. Authenticated trips
+	// (and the pre-login /auth/* limiter) fall through to the plain retry recovery.
+	RATE_LIMITED: (_msg, ctx = {}) => ctx.login_helps
+		? recovery(
+			LOGIN,
+			'You hit the anonymous rate limit. Sign in or create a free account for a much higher limit, then re-run.',
+			{
+				retry_after_seconds: ctx.retry_after_seconds || 30,
+				commands: ['npx happyskills login --browser --json'],
+			}
+		)
+		: recovery(
+			RETRY,
+			'Rate limit reached. Retry after the suggested interval.',
+			{ retry_after_seconds: ctx.retry_after_seconds || 30, max_attempts: 3 }
+		),
 	DB_UNAVAILABLE: () => recovery(
 		RETRY,
 		'The registry database is temporarily unavailable. Retry shortly.',

package/src/constants/next_step_by_error_code.test.js

@@ -7,7 +7,7 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
 const { next_step_for_error } = require('./next_step_by_error_code')
-const { DISCOVER_SCHEMA, ROUTING, kind_for_action } = require('./next_step_actions')
+const { DISCOVER_SCHEMA, ROUTING, RECOVERY, LOGIN, RETRY, kind_for_action } = require('./next_step_actions')
 
 describe('next_step_by_error_code — schema discovery routing', () => {
 	it('discover_schema is a routing-kind action', () => {
@@ -28,3 +28,19 @@ describe('next_step_by_error_code — schema discovery routing', () => {
 		})
 	}
 })
+
+describe('next_step_by_error_code — RATE_LIMITED steers anonymous callers to sign in', () => {
+	it('login_helps → a LOGIN recovery that points at `happyskills login`', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { login_helps: true, retry_after_seconds: 42 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, LOGIN)
+		assert.ok(ns.context.commands.some(c => c.includes('login')), 'must point at the login command')
+		assert.strictEqual(ns.context.retry_after_seconds, 42)
+	})
+
+	it('without login_helps → a plain RETRY recovery (authenticated / auth-path trips)', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { retry_after_seconds: 30 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, RETRY)
+	})
+})