@codetunezstudios/token-kit 0.1.0-beta.2 → 0.1.0-beta.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Codetunez Studios
-
-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
+MIT License
+
+Copyright (c) 2025-2026 Codetunez Studios
+
+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,261 +1,263 @@
-# @codetunezstudios/token-kit
-
-[![npm version](https://img.shields.io/npm/v/@codetunezstudios/token-kit.svg)](https://www.npmjs.com/package/@codetunezstudios/token-kit)
-[![license](https://img.shields.io/npm/l/@codetunezstudios/token-kit.svg)](https://github.com/codetunez-studios/token-kit/blob/main/LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)
-
-> **Beta** — This SDK is under active development. APIs may change before 1.0.
-
-Official TypeScript/JavaScript SDK for [token-kit](https://token-kit.com) — the AI token infrastructure platform for developers.
-
-token-kit enables developers to integrate LLM features into their applications using an end-user-funded token model. Users purchase tokens, developers consume them for AI operations.
-
-## Features
-
-- **Simple API** — Intuitive methods for chat completions
-- **TypeScript First** — Full type safety and IntelliSense support
-- **Multiple Models** — Support for Claude, GPT-4o, Amazon Nova (more coming)
-- **Token Management** — Built-in balance checking and validation
-- **Error Handling** — Comprehensive typed error classes
-- **Lightweight** — Single runtime dependency (axios)
-
-## Installation
-
-```bash
-npm install @codetunezstudios/token-kit
-```
-
-```bash
-yarn add @codetunezstudios/token-kit
-```
-
-```bash
-pnpm add @codetunezstudios/token-kit
-```
-
-## Quick Start
-
-```typescript
-import TokenKit from '@codetunezstudios/token-kit';
-
-// Initialize with your developer API key
-const tk = new TokenKit({
-  apiKey: process.env.TOKENKIT_API_KEY!,
-});
-
-// Make a chat request
-const res = await tk.chat('user_token_here', [
-  TokenKit.user('What is token-kit?'),
-]);
-
-console.log(res.message.content);
-console.log('Tokens used:', res.tokensDeducted);
-console.log('Balance:', res.userBalance);
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-const tk = new TokenKit(config);
-```
-
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `apiKey` | `string` | Yes | — | Developer API key |
-| `baseUrl` | `string` | No | `https://api.token-kit.com/api/v1` | API base URL |
-| `timeout` | `number` | No | `60000` | Request timeout (ms) |
-
-### Methods
-
-#### `tk.chat(userToken, messages, options?)`
-
-Send a chat completion request.
-
-```typescript
-const res = await tk.chat('user_token', [
-  TokenKit.system('You are a helpful assistant.'),
-  TokenKit.user('Explain quantum computing simply.'),
-], {
-  model: 'gpt-4o',
-  maxTokens: 200,
-  temperature: 0.8,
-});
-```
-
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `model` | `string` | `gpt-4o-mini` | LLM model to use |
-| `maxTokens` | `number` | `500` | Max tokens in response |
-| `temperature` | `number` | `0.7` | Randomness (0–2) |
-
-**Returns** `ChatResponse`:
-
-```typescript
-{
-  id: string;
-  model: string;
-  message: { role: 'assistant'; content: string };
-  tokensUsed: { prompt: number; completion: number; total: number };
-  tokensDeducted: number;
-  finishReason: string;
-  userBalance?: number;
-  latency?: number;
-}
-```
-
-#### `tk.setUserToken(userToken)`
-
-Set the user token for subsequent requests so you don't have to pass it each time.
-
-```typescript
-tk.setUserToken('user_token');
-
-// Now you can omit the userToken parameter
-const res = await tk.chat([TokenKit.user('Hello!')]);
-```
-
-#### `tk.validateToken(userToken?)`
-
-Validate a user token and check balance/limits.
-
-```typescript
-const info = await tk.validateToken('user_token');
-if (info.valid) {
-  console.log('Balance:', info.balance);
-}
-```
-
-#### `tk.getBalance(userToken?)`
-
-Get the current token balance.
-
-```typescript
-const balance = await tk.getBalance('user_token');
-```
-
-#### `tk.getModels()`
-
-List available LLM models.
-
-```typescript
-const models = await tk.getModels();
-// ['gpt-4o-mini', 'gpt-4o', 'claude-3.5-haiku', 'claude-sonnet-4', 'nova-micro', 'nova-lite']
-```
-
-### Helper Methods
-
-```typescript
-TokenKit.user('message')       // { role: 'user', content: 'message' }
-TokenKit.system('message')     // { role: 'system', content: 'message' }
-TokenKit.assistant('message')  // { role: 'assistant', content: 'message' }
-```
-
-## Error Handling
-
-```typescript
-import TokenKit, { TokenKitAPIError } from '@codetunezstudios/token-kit';
-
-try {
-  const res = await tk.chat(userToken, messages);
-} catch (err) {
-  if (err instanceof TokenKitAPIError) {
-    console.error(err.code);       // 'INSUFFICIENT_BALANCE'
-    console.error(err.statusCode); // 402
-    console.error(err.message);    // 'Insufficient token balance'
-  }
-}
-```
-
-**Error codes:**
-
-| Code | Status | Description |
-|------|--------|-------------|
-| `INVALID_API_KEY` | 401 | Developer API key is invalid |
-| `INVALID_TOKEN` | 401 | User token is invalid or expired |
-| `INSUFFICIENT_BALANCE` | 402 | Not enough tokens |
-| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
-| `DAILY_LIMIT_EXCEEDED` | 429 | Daily spending limit reached |
-| `MONTHLY_LIMIT_EXCEEDED` | 429 | Monthly spending limit reached |
-| `MODEL_NOT_SUPPORTED` | 400 | Requested model is not available |
-| `TIMEOUT` | 504 | Request timed out |
-| `NETWORK_ERROR` | 503 | Cannot reach token-kit API |
-
-## Express Integration Example
-
-```typescript
-import express from 'express';
-import TokenKit from '@codetunezstudios/token-kit';
-
-const app = express();
-const tk = new TokenKit({ apiKey: process.env.TOKENKIT_API_KEY! });
-
-app.post('/api/chat', async (req, res) => {
-  try {
-    const { userToken, message } = req.body;
-    const result = await tk.chat(userToken, [TokenKit.user(message)]);
-    res.json({ reply: result.message.content, balance: result.userBalance });
-  } catch (err) {
-    res.status(500).json({ error: 'Chat failed' });
-  }
-});
-```
-
-> **Security:** Never expose your developer API key in client-side code. Always proxy requests through your backend.
-
-## Token Pricing
-
-Different models consume tokens at different rates:
-
-| Model | Rate | 1,000 TK tokens = |
-|-------|------|-------------------|
-| GPT-4o Mini | 1.0x | 1,000 LLM tokens |
-| Claude 3.5 Haiku | 1.0x | 1,000 LLM tokens |
-| Amazon Nova Micro | 1.0x | 1,000 LLM tokens |
-| Amazon Nova Lite | 1.0x | 1,000 LLM tokens |
-| GPT-4o | 2.0x | 500 LLM tokens |
-| Claude Sonnet 4 | 3.0x | 333 LLM tokens |
-
-See [token-kit.com](https://token-kit.com) for current package pricing and details.
-
-## Requirements
-
-- Node.js >= 18
-- TypeScript >= 5.0 (recommended)
-
-## Development
-
-```bash
-git clone https://github.com/codetunez-studios/token-kit.git
-cd token-kit
-npm install     # Install dependencies
-npm run build   # Build (CJS + ESM + types)
-npm test        # Run tests
-npm run typecheck  # Type checking
-```
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/my-feature`)
-3. Commit your changes (`git commit -m 'Add my feature'`)
-4. Push to the branch (`git push origin feature/my-feature`)
-5. Open a Pull Request
-
-## License
-
-[MIT](LICENSE) © [Codetunez Studios](https://github.com/codetunez-studios)
-
-## Links
-
-- [token-kit Platform](https://token-kit.com)
-- [User Token Portal](https://ai-tokens.me)
-- [Documentation](https://token-kit.com/sdk)
-- [npm Package](https://www.npmjs.com/package/@codetunezstudios/token-kit)
-- [GitHub Issues](https://github.com/codetunez-studios/token-kit/issues)
+# @codetunezstudios/token-kit
+
+[![npm version](https://img.shields.io/npm/v/@codetunezstudios/token-kit.svg)](https://www.npmjs.com/package/@codetunezstudios/token-kit)
+[![license](https://img.shields.io/npm/l/@codetunezstudios/token-kit.svg)](https://github.com/codetunez-studios/token-kit/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)
+
+> **Beta** — This SDK is under active development. APIs may change before 1.0.
+
+Official TypeScript/JavaScript SDK for [token-kit](https://token-kit.com) — an AI billing and metering platform for developers.
+
+token-kit enables developers to integrate LLM features with prepaid user-funded credits, spend controls, and cost visibility. It is especially useful for indie developers and small teams that want AI monetization without taking uncapped provider risk.
+
+If your users already bring their own OpenAI or Anthropic keys, that can still be a valid approach. token-kit is best when you want one billing, routing, and control layer without exposing provider key management to end-users.
+
+## Features
+
+- **Simple API** — Intuitive methods for chat completions
+- **TypeScript First** — Full type safety and IntelliSense support
+- **Multiple Models** — Support for Claude, GPT-4o, Amazon Nova (more coming)
+- **Token Management** — Built-in balance checking and validation
+- **Error Handling** — Comprehensive typed error classes
+- **Lightweight** — Single runtime dependency (axios)
+
+## Installation
+
+```bash
+npm install @codetunezstudios/token-kit
+```
+
+```bash
+yarn add @codetunezstudios/token-kit
+```
+
+```bash
+pnpm add @codetunezstudios/token-kit
+```
+
+## Quick Start
+
+```typescript
+import TokenKit from '@codetunezstudios/token-kit';
+
+// Initialize with your developer API key
+const tk = new TokenKit({
+  apiKey: process.env.TOKENKIT_API_KEY!,
+});
+
+// Make a chat request
+const res = await tk.chat('user_token_here', [
+  TokenKit.user('What is token-kit?'),
+]);
+
+console.log(res.message.content);
+console.log('Tokens used:', res.tokensDeducted);
+console.log('Balance:', res.userBalance);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+const tk = new TokenKit(config);
+```
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `apiKey` | `string` | Yes | — | Developer API key |
+| `baseUrl` | `string` | No | `https://api.token-kit.com/api/v1` | API base URL |
+| `timeout` | `number` | No | `60000` | Request timeout (ms) |
+
+### Methods
+
+#### `tk.chat(userToken, messages, options?)`
+
+Send a chat completion request.
+
+```typescript
+const res = await tk.chat('user_token', [
+  TokenKit.system('You are a helpful assistant.'),
+  TokenKit.user('Explain quantum computing simply.'),
+], {
+  model: 'gpt-4o',
+  maxTokens: 200,
+  temperature: 0.8,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | `gpt-4o-mini` | LLM model to use |
+| `maxTokens` | `number` | `500` | Max tokens in response |
+| `temperature` | `number` | `0.7` | Randomness (0–2) |
+
+**Returns** `ChatResponse`:
+
+```typescript
+{
+  id: string;
+  model: string;
+  message: { role: 'assistant'; content: string };
+  tokensUsed: { prompt: number; completion: number; total: number };
+  tokensDeducted: number;
+  finishReason: string;
+  userBalance?: number;
+  latency?: number;
+}
+```
+
+#### `tk.setUserToken(userToken)`
+
+Set the user token for subsequent requests so you don't have to pass it each time.
+
+```typescript
+tk.setUserToken('user_token');
+
+// Now you can omit the userToken parameter
+const res = await tk.chat([TokenKit.user('Hello!')]);
+```
+
+#### `tk.validateToken(userToken?)`
+
+Validate a user token and check balance/limits.
+
+```typescript
+const info = await tk.validateToken('user_token');
+if (info.valid) {
+  console.log('Balance:', info.balance);
+}
+```
+
+#### `tk.getBalance(userToken?)`
+
+Get the current token balance.
+
+```typescript
+const balance = await tk.getBalance('user_token');
+```
+
+#### `tk.getModels()`
+
+List available LLM models.
+
+```typescript
+const models = await tk.getModels();
+// ['gpt-4o-mini', 'gpt-4o', 'claude-3.5-haiku', 'claude-sonnet-4', 'nova-micro', 'nova-lite']
+```
+
+### Helper Methods
+
+```typescript
+TokenKit.user('message')       // { role: 'user', content: 'message' }
+TokenKit.system('message')     // { role: 'system', content: 'message' }
+TokenKit.assistant('message')  // { role: 'assistant', content: 'message' }
+```
+
+## Error Handling
+
+```typescript
+import TokenKit, { TokenKitAPIError } from '@codetunezstudios/token-kit';
+
+try {
+  const res = await tk.chat(userToken, messages);
+} catch (err) {
+  if (err instanceof TokenKitAPIError) {
+    console.error(err.code);       // 'INSUFFICIENT_BALANCE'
+    console.error(err.statusCode); // 402
+    console.error(err.message);    // 'Insufficient token balance'
+  }
+}
+```
+
+**Error codes:**
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `INVALID_API_KEY` | 401 | Developer API key is invalid |
+| `INVALID_TOKEN` | 401 | User token is invalid or expired |
+| `INSUFFICIENT_BALANCE` | 402 | Not enough tokens |
+| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
+| `DAILY_LIMIT_EXCEEDED` | 429 | Daily spending limit reached |
+| `MONTHLY_LIMIT_EXCEEDED` | 429 | Monthly spending limit reached |
+| `MODEL_NOT_SUPPORTED` | 400 | Requested model is not available |
+| `TIMEOUT` | 504 | Request timed out |
+| `NETWORK_ERROR` | 503 | Cannot reach token-kit API |
+
+## Express Integration Example
+
+```typescript
+import express from 'express';
+import TokenKit from '@codetunezstudios/token-kit';
+
+const app = express();
+const tk = new TokenKit({ apiKey: process.env.TOKENKIT_API_KEY! });
+
+app.post('/api/chat', async (req, res) => {
+  try {
+    const { userToken, message } = req.body;
+    const result = await tk.chat(userToken, [TokenKit.user(message)]);
+    res.json({ reply: result.message.content, balance: result.userBalance });
+  } catch (err) {
+    res.status(500).json({ error: 'Chat failed' });
+  }
+});
+```
+
+> **Security:** Never expose your developer API key in client-side code. Always proxy requests through your backend.
+
+## Token Pricing
+
+Different models consume tokens at different rates:
+
+| Model | Rate | 1,000 TK tokens = |
+|-------|------|-------------------|
+| GPT-4o Mini | 1.0x | 1,000 LLM tokens |
+| Claude 3.5 Haiku | 1.0x | 1,000 LLM tokens |
+| Amazon Nova Micro | 1.0x | 1,000 LLM tokens |
+| Amazon Nova Lite | 1.0x | 1,000 LLM tokens |
+| GPT-4o | 2.0x | 500 LLM tokens |
+| Claude Sonnet 4 | 3.0x | 333 LLM tokens |
+
+See [token-kit.com](https://token-kit.com) for current package pricing and details.
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0 (recommended)
+
+## Development
+
+```bash
+git clone https://github.com/codetunez-studios/token-kit.git
+cd token-kit
+npm install     # Install dependencies
+npm run build   # Build (CJS + ESM + types)
+npm test        # Run tests
+npm run typecheck  # Type checking
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -m 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+## License
+
+[MIT](LICENSE) © [Codetunez Studios](https://github.com/codetunez-studios)
+
+## Links
+
+- [token-kit Platform](https://token-kit.com)
+- [User Token Portal](https://ai-tokens.me)
+- [Documentation](https://token-kit.com/sdk)
+- [npm Package](https://www.npmjs.com/package/@codetunezstudios/token-kit)
+- [GitHub Issues](https://github.com/codetunez-studios/token-kit/issues)

package/dist/index.d.mts

@@ -86,15 +86,93 @@ declare class TokenKitAPIError extends Error implements TokenKitError {
     details?: unknown;
     constructor(message: string, code: string, statusCode?: number, details?: unknown);
 }
+/**
+ * Named deployment environments.
+ * Maps to the canonical API Gateway URLs for each environment.
+ * Use `baseUrl` to override for self-hosted or custom deployments.
+ */
+type TokenKitEnvironment = 'production' | 'staging' | 'development';
+/** Canonical base URLs per environment — exported for reference */
+declare const ENVIRONMENT_URLS: Record<TokenKitEnvironment, string>;
 interface TokenKitConfig {
     /** Developer API key */
     apiKey: string;
-    /** API Gateway base URL (default: https://api.token-kit.com/api/v1) */
+    /**
+     * Named environment shorthand. Resolves to the canonical API URL.
+     * Ignored when `baseUrl` is also provided (baseUrl takes precedence).
+     * Defaults to `'production'` when neither is set.
+     */
+    environment?: TokenKitEnvironment;
+    /**
+     * Explicit API Gateway base URL.
+     * Use this for self-hosted deployments or local development.
+     * Takes precedence over `environment`.
+     */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 60000) */
     timeout?: number;
 }
 
+/**
+ * Token-Kit SDK — Portal Connect Helper
+ *
+ * Opens a popup to the ai-tokens.me /connect page, listens for the
+ * TOKEN_KIT_TOKEN postMessage from the portal, stores the token in
+ * localStorage, and resolves a promise with the token string.
+ *
+ * Rejects with TokenKitConnectCancelledError if the user closes the
+ * popup without confirming.
+ *
+ * Usage:
+ * ```typescript
+ * import { connectViaPortal } from '@codetunezstudios/token-kit';
+ *
+ * const userToken = await connectViaPortal({ appId: 'dev_abc123...' });
+ * tokenKit.setUserToken(userToken);
+ * ```
+ */
+interface ConnectViaPortalOptions {
+    /** The developerId of the requesting app (shown in admin CLI output). */
+    appId: string;
+    /**
+     * Base URL of the Token-Kit portal.
+     * Defaults to 'https://ai-tokens.me'.
+     * Override for local development: 'http://localhost:3000'
+     */
+    portalUrl?: string;
+}
+/**
+ * Thrown by connectViaPortal() when the user closes the popup without
+ * clicking "Allow Access".
+ */
+declare class TokenKitConnectCancelledError extends Error {
+    constructor();
+}
+/**
+ * Open a Token-Kit portal popup to acquire a user token via postMessage.
+ *
+ * Flow:
+ *  1. Opens `${portalUrl}/connect?appId=...&origin=...` as a 480×640 popup
+ *  2. Listens for `message` events filtered to the portal origin and
+ *     `type === 'TOKEN_KIT_TOKEN'`
+ *  3. On receipt: stores token in localStorage, resolves with the token string
+ *  4. If popup is closed without a message: rejects with TokenKitConnectCancelledError
+ *
+ * @param options - Connection options
+ * @returns Promise that resolves with the user token string
+ */
+declare function connectViaPortal(options: ConnectViaPortalOptions): Promise<string>;
+/**
+ * Retrieve the most recently connected user token from localStorage.
+ * Returns null if no token has been stored via connectViaPortal().
+ */
+declare function getStoredUserToken(): string | null;
+/**
+ * Clear the stored user token from localStorage.
+ * Call this on logout.
+ */
+declare function clearStoredUserToken(): void;
+
 /**
  * Token-Kit SDK - Main Entry Point
  * Official TypeScript SDK for Token-Kit platform
@@ -122,7 +200,11 @@ declare class TokenKit {
      *
      * @param config - Configuration options
      * @param config.apiKey - Your developer API key
-     * @param config.baseUrl - API base URL (optional, defaults to production)
+     * @param config.environment - Target environment: 'production' | 'staging' | 'development'
+     *   Resolves to the canonical API URL for that environment.
+     *   Defaults to 'production'. Ignored when `baseUrl` is also set.
+     * @param config.baseUrl - Explicit API base URL — overrides `environment`.
+     *   Use for self-hosted deployments or local tunnels.
      * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
      */
     constructor(config: TokenKitConfig);
@@ -229,4 +311,4 @@ declare class TokenKit {
     static assistant(content: string): Message;
 }
 
-export { type ChatOptions, type ChatResponse, type Message, type MessageRole, type ModelInfo, type ModelsResponse, TokenKit, TokenKitAPIError, type TokenKitConfig, type TokenValidationResponse, TokenKit as default };
+export { type ChatOptions, type ChatResponse, type ConnectViaPortalOptions, ENVIRONMENT_URLS, type Message, type MessageRole, type ModelInfo, type ModelsResponse, TokenKit, TokenKitAPIError, type TokenKitConfig, TokenKitConnectCancelledError, type TokenKitEnvironment, type TokenValidationResponse, clearStoredUserToken, connectViaPortal, TokenKit as default, getStoredUserToken };

package/dist/index.d.ts

@@ -86,15 +86,93 @@ declare class TokenKitAPIError extends Error implements TokenKitError {
     details?: unknown;
     constructor(message: string, code: string, statusCode?: number, details?: unknown);
 }
+/**
+ * Named deployment environments.
+ * Maps to the canonical API Gateway URLs for each environment.
+ * Use `baseUrl` to override for self-hosted or custom deployments.
+ */
+type TokenKitEnvironment = 'production' | 'staging' | 'development';
+/** Canonical base URLs per environment — exported for reference */
+declare const ENVIRONMENT_URLS: Record<TokenKitEnvironment, string>;
 interface TokenKitConfig {
     /** Developer API key */
     apiKey: string;
-    /** API Gateway base URL (default: https://api.token-kit.com/api/v1) */
+    /**
+     * Named environment shorthand. Resolves to the canonical API URL.
+     * Ignored when `baseUrl` is also provided (baseUrl takes precedence).
+     * Defaults to `'production'` when neither is set.
+     */
+    environment?: TokenKitEnvironment;
+    /**
+     * Explicit API Gateway base URL.
+     * Use this for self-hosted deployments or local development.
+     * Takes precedence over `environment`.
+     */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 60000) */
     timeout?: number;
 }
 
+/**
+ * Token-Kit SDK — Portal Connect Helper
+ *
+ * Opens a popup to the ai-tokens.me /connect page, listens for the
+ * TOKEN_KIT_TOKEN postMessage from the portal, stores the token in
+ * localStorage, and resolves a promise with the token string.
+ *
+ * Rejects with TokenKitConnectCancelledError if the user closes the
+ * popup without confirming.
+ *
+ * Usage:
+ * ```typescript
+ * import { connectViaPortal } from '@codetunezstudios/token-kit';
+ *
+ * const userToken = await connectViaPortal({ appId: 'dev_abc123...' });
+ * tokenKit.setUserToken(userToken);
+ * ```
+ */
+interface ConnectViaPortalOptions {
+    /** The developerId of the requesting app (shown in admin CLI output). */
+    appId: string;
+    /**
+     * Base URL of the Token-Kit portal.
+     * Defaults to 'https://ai-tokens.me'.
+     * Override for local development: 'http://localhost:3000'
+     */
+    portalUrl?: string;
+}
+/**
+ * Thrown by connectViaPortal() when the user closes the popup without
+ * clicking "Allow Access".
+ */
+declare class TokenKitConnectCancelledError extends Error {
+    constructor();
+}
+/**
+ * Open a Token-Kit portal popup to acquire a user token via postMessage.
+ *
+ * Flow:
+ *  1. Opens `${portalUrl}/connect?appId=...&origin=...` as a 480×640 popup
+ *  2. Listens for `message` events filtered to the portal origin and
+ *     `type === 'TOKEN_KIT_TOKEN'`
+ *  3. On receipt: stores token in localStorage, resolves with the token string
+ *  4. If popup is closed without a message: rejects with TokenKitConnectCancelledError
+ *
+ * @param options - Connection options
+ * @returns Promise that resolves with the user token string
+ */
+declare function connectViaPortal(options: ConnectViaPortalOptions): Promise<string>;
+/**
+ * Retrieve the most recently connected user token from localStorage.
+ * Returns null if no token has been stored via connectViaPortal().
+ */
+declare function getStoredUserToken(): string | null;
+/**
+ * Clear the stored user token from localStorage.
+ * Call this on logout.
+ */
+declare function clearStoredUserToken(): void;
+
 /**
  * Token-Kit SDK - Main Entry Point
  * Official TypeScript SDK for Token-Kit platform
@@ -122,7 +200,11 @@ declare class TokenKit {
      *
      * @param config - Configuration options
      * @param config.apiKey - Your developer API key
-     * @param config.baseUrl - API base URL (optional, defaults to production)
+     * @param config.environment - Target environment: 'production' | 'staging' | 'development'
+     *   Resolves to the canonical API URL for that environment.
+     *   Defaults to 'production'. Ignored when `baseUrl` is also set.
+     * @param config.baseUrl - Explicit API base URL — overrides `environment`.
+     *   Use for self-hosted deployments or local tunnels.
      * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
      */
     constructor(config: TokenKitConfig);
@@ -229,4 +311,4 @@ declare class TokenKit {
     static assistant(content: string): Message;
 }
 
-export { type ChatOptions, type ChatResponse, type Message, type MessageRole, type ModelInfo, type ModelsResponse, TokenKit, TokenKitAPIError, type TokenKitConfig, type TokenValidationResponse, TokenKit as default };
+export { type ChatOptions, type ChatResponse, type ConnectViaPortalOptions, ENVIRONMENT_URLS, type Message, type MessageRole, type ModelInfo, type ModelsResponse, TokenKit, TokenKitAPIError, type TokenKitConfig, TokenKitConnectCancelledError, type TokenKitEnvironment, type TokenValidationResponse, clearStoredUserToken, connectViaPortal, TokenKit as default, getStoredUserToken };

package/dist/index.js

@@ -30,9 +30,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ENVIRONMENT_URLS: () => ENVIRONMENT_URLS,
   TokenKit: () => TokenKit,
   TokenKitAPIError: () => TokenKitAPIError,
-  default: () => index_default
+  TokenKitConnectCancelledError: () => TokenKitConnectCancelledError,
+  clearStoredUserToken: () => clearStoredUserToken,
+  connectViaPortal: () => connectViaPortal,
+  default: () => index_default,
+  getStoredUserToken: () => getStoredUserToken
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -50,6 +55,11 @@ var TokenKitAPIError = class extends Error {
     Error.captureStackTrace?.(this, this.constructor);
   }
 };
+var ENVIRONMENT_URLS = {
+  production: "https://api.token-kit.com/v1",
+  staging: "https://api-staging.token-kit.com/v1",
+  development: "https://api-dev.token-kit.com/v1"
+};
 
 // src/client.ts
 var TokenKitClient = class {
@@ -58,8 +68,9 @@ var TokenKitClient = class {
       throw new Error("API key is required");
     }
     this.apiKey = config.apiKey;
+    const baseURL = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "production"];
     this.client = import_axios.default.create({
-      baseURL: config.baseUrl || "https://api.token-kit.com/api/v1",
+      baseURL,
       timeout: config.timeout || 6e4,
       headers: {
         "Content-Type": "application/json",
@@ -196,6 +207,67 @@ var TokenKitClient = class {
   }
 };
 
+// src/connect.ts
+var TokenKitConnectCancelledError = class _TokenKitConnectCancelledError extends Error {
+  constructor() {
+    super("User closed the Token-Kit connect popup without confirming.");
+    this.name = "TokenKitConnectCancelledError";
+    Object.setPrototypeOf(this, _TokenKitConnectCancelledError.prototype);
+  }
+};
+var STORAGE_KEY = "tokenkit_user_token";
+async function connectViaPortal(options) {
+  const portalUrl = (options.portalUrl ?? "https://ai-tokens.me").replace(/\/$/, "");
+  const currentOrigin = encodeURIComponent(window.location.origin);
+  const url = `${portalUrl}/connect?appId=${encodeURIComponent(options.appId)}&origin=${currentOrigin}`;
+  const popup = window.open(
+    url,
+    "tokenkit-connect",
+    "width=480,height=640,scrollbars=no,resizable=no,status=no,toolbar=no,menubar=no"
+  );
+  if (!popup) {
+    throw new Error(
+      "Failed to open Token-Kit connect popup. Ensure popups are allowed for this origin, or call connectViaPortal() directly from a user gesture (e.g. button click)."
+    );
+  }
+  return new Promise((resolve, reject) => {
+    function onMessage(event) {
+      if (event.origin !== new URL(portalUrl).origin) return;
+      const data = event.data;
+      if (data?.type !== "TOKEN_KIT_TOKEN" || typeof data.token !== "string" || !data.token) {
+        return;
+      }
+      cleanup();
+      localStorage.setItem(STORAGE_KEY, data.token);
+      resolve(data.token);
+    }
+    const pollInterval = setInterval(() => {
+      if (popup.closed) {
+        cleanup();
+        reject(new TokenKitConnectCancelledError());
+      }
+    }, 400);
+    function cleanup() {
+      window.removeEventListener("message", onMessage);
+      clearInterval(pollInterval);
+    }
+    window.addEventListener("message", onMessage);
+  });
+}
+function getStoredUserToken() {
+  try {
+    return localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+function clearStoredUserToken() {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+  }
+}
+
 // src/index.ts
 var TokenKit = class {
   /**
@@ -203,7 +275,11 @@ var TokenKit = class {
    * 
    * @param config - Configuration options
    * @param config.apiKey - Your developer API key
-   * @param config.baseUrl - API base URL (optional, defaults to production)
+   * @param config.environment - Target environment: 'production' | 'staging' | 'development'
+   *   Resolves to the canonical API URL for that environment.
+   *   Defaults to 'production'. Ignored when `baseUrl` is also set.
+   * @param config.baseUrl - Explicit API base URL — overrides `environment`.
+   *   Use for self-hosted deployments or local tunnels.
    * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
    */
   constructor(config) {
@@ -354,6 +430,11 @@ var TokenKit = class {
 var index_default = TokenKit;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ENVIRONMENT_URLS,
   TokenKit,
-  TokenKitAPIError
+  TokenKitAPIError,
+  TokenKitConnectCancelledError,
+  clearStoredUserToken,
+  connectViaPortal,
+  getStoredUserToken
 });

package/dist/index.mjs

@@ -12,6 +12,11 @@ var TokenKitAPIError = class extends Error {
     Error.captureStackTrace?.(this, this.constructor);
   }
 };
+var ENVIRONMENT_URLS = {
+  production: "https://api.token-kit.com/v1",
+  staging: "https://api-staging.token-kit.com/v1",
+  development: "https://api-dev.token-kit.com/v1"
+};
 
 // src/client.ts
 var TokenKitClient = class {
@@ -20,8 +25,9 @@ var TokenKitClient = class {
       throw new Error("API key is required");
     }
     this.apiKey = config.apiKey;
+    const baseURL = config.baseUrl ?? ENVIRONMENT_URLS[config.environment ?? "production"];
     this.client = axios.create({
-      baseURL: config.baseUrl || "https://api.token-kit.com/api/v1",
+      baseURL,
       timeout: config.timeout || 6e4,
       headers: {
         "Content-Type": "application/json",
@@ -158,6 +164,67 @@ var TokenKitClient = class {
   }
 };
 
+// src/connect.ts
+var TokenKitConnectCancelledError = class _TokenKitConnectCancelledError extends Error {
+  constructor() {
+    super("User closed the Token-Kit connect popup without confirming.");
+    this.name = "TokenKitConnectCancelledError";
+    Object.setPrototypeOf(this, _TokenKitConnectCancelledError.prototype);
+  }
+};
+var STORAGE_KEY = "tokenkit_user_token";
+async function connectViaPortal(options) {
+  const portalUrl = (options.portalUrl ?? "https://ai-tokens.me").replace(/\/$/, "");
+  const currentOrigin = encodeURIComponent(window.location.origin);
+  const url = `${portalUrl}/connect?appId=${encodeURIComponent(options.appId)}&origin=${currentOrigin}`;
+  const popup = window.open(
+    url,
+    "tokenkit-connect",
+    "width=480,height=640,scrollbars=no,resizable=no,status=no,toolbar=no,menubar=no"
+  );
+  if (!popup) {
+    throw new Error(
+      "Failed to open Token-Kit connect popup. Ensure popups are allowed for this origin, or call connectViaPortal() directly from a user gesture (e.g. button click)."
+    );
+  }
+  return new Promise((resolve, reject) => {
+    function onMessage(event) {
+      if (event.origin !== new URL(portalUrl).origin) return;
+      const data = event.data;
+      if (data?.type !== "TOKEN_KIT_TOKEN" || typeof data.token !== "string" || !data.token) {
+        return;
+      }
+      cleanup();
+      localStorage.setItem(STORAGE_KEY, data.token);
+      resolve(data.token);
+    }
+    const pollInterval = setInterval(() => {
+      if (popup.closed) {
+        cleanup();
+        reject(new TokenKitConnectCancelledError());
+      }
+    }, 400);
+    function cleanup() {
+      window.removeEventListener("message", onMessage);
+      clearInterval(pollInterval);
+    }
+    window.addEventListener("message", onMessage);
+  });
+}
+function getStoredUserToken() {
+  try {
+    return localStorage.getItem(STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+function clearStoredUserToken() {
+  try {
+    localStorage.removeItem(STORAGE_KEY);
+  } catch {
+  }
+}
+
 // src/index.ts
 var TokenKit = class {
   /**
@@ -165,7 +232,11 @@ var TokenKit = class {
    * 
    * @param config - Configuration options
    * @param config.apiKey - Your developer API key
-   * @param config.baseUrl - API base URL (optional, defaults to production)
+   * @param config.environment - Target environment: 'production' | 'staging' | 'development'
+   *   Resolves to the canonical API URL for that environment.
+   *   Defaults to 'production'. Ignored when `baseUrl` is also set.
+   * @param config.baseUrl - Explicit API base URL — overrides `environment`.
+   *   Use for self-hosted deployments or local tunnels.
    * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
    */
   constructor(config) {
@@ -315,7 +386,12 @@ var TokenKit = class {
 };
 var index_default = TokenKit;
 export {
+  ENVIRONMENT_URLS,
   TokenKit,
   TokenKitAPIError,
-  index_default as default
+  TokenKitConnectCancelledError,
+  clearStoredUserToken,
+  connectViaPortal,
+  index_default as default,
+  getStoredUserToken
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@codetunezstudios/token-kit",
-    "version": "0.1.0-beta.2",
+    "version": "0.1.0-beta.4",
     "description": "Official TypeScript SDK for token-kit - AI token infrastructure for developers",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -57,7 +57,8 @@
         "access": "public"
     },
     "dependencies": {
-        "axios": "^1.6.5"
+        "axios": "^1.6.5",
+        "jest-environment-jsdom": "^30.3.0"
     },
     "devDependencies": {
         "@types/express": "^5.0.6",