@codetunezstudios/token-kit 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Token-Kit SDK - Type Definitions
+ * TypeScript types for the Token-Kit SDK
+ */
+type MessageRole = 'system' | 'user' | 'assistant';
+interface Message {
+    role: MessageRole;
+    content: string;
+}
+interface ChatOptions {
+    /** LLM model to use (default: 'gpt-3.5-turbo') */
+    model?: string;
+    /** Maximum tokens in response (default: 500) */
+    maxTokens?: number;
+    /** Temperature for response randomness 0-2 (default: 0.7) */
+    temperature?: number;
+}
+interface ChatResponse {
+    /** Unique chat completion ID */
+    id: string;
+    /** Model used for completion */
+    model: string;
+    /** Assistant's response message */
+    message: Message;
+    /** Token usage statistics */
+    tokensUsed: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    /** Number of tokens deducted from user balance */
+    tokensDeducted: number;
+    /** Reason completion finished */
+    finishReason: string;
+    /** User's remaining token balance */
+    userBalance?: number;
+    /** Response latency in milliseconds */
+    latency?: number;
+}
+interface TokenValidationResponse {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** User information */
+    user?: {
+        id: string;
+        email: string;
+    };
+    /** Current token balance */
+    balance?: number;
+    /** Daily spending so far */
+    dailySpending?: number;
+    /** Monthly spending so far */
+    monthlySpending?: number;
+    /** Spending limits */
+    limits?: {
+        dailyLimit: number;
+        monthlyLimit: number;
+        perRequestLimit: number;
+    };
+}
+interface ModelInfo {
+    /** Model identifier */
+    name: string;
+    /** Human-readable model name */
+    displayName: string;
+    /** Token rate multiplier */
+    tokenRate: number;
+    /** Default max tokens */
+    defaultMaxTokens: number;
+}
+interface ModelsResponse {
+    models: string[];
+    count: number;
+}
+interface TokenKitError extends Error {
+    /** Error code */
+    code: string;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Additional error details */
+    details?: unknown;
+}
+declare class TokenKitAPIError extends Error implements TokenKitError {
+    code: string;
+    statusCode?: number;
+    details?: unknown;
+    constructor(message: string, code: string, statusCode?: number, details?: unknown);
+}
+interface TokenKitConfig {
+    /** Developer API key */
+    apiKey: string;
+    /** API Gateway base URL (default: https://api.token-kit.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+
+/**
+ * Token-Kit SDK - Main Entry Point
+ * Official TypeScript SDK for Token-Kit platform
+ */
+
+/**
+ * TokenKit - Main SDK class
+ *
+ * Example usage:
+ * ```typescript
+ * const tokenKit = new TokenKit({ apiKey: 'your-api-key' });
+ *
+ * const response = await tokenKit.chat('user-token', [
+ *   { role: 'user', content: 'Hello!' }
+ * ]);
+ *
+ * console.log(response.message.content);
+ * ```
+ */
+declare class TokenKit {
+    private client;
+    private userToken;
+    /**
+     * Create a new TokenKit instance
+     *
+     * @param config - Configuration options
+     * @param config.apiKey - Your developer API key
+     * @param config.baseUrl - API base URL (optional, defaults to production)
+     * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
+     */
+    constructor(config: TokenKitConfig);
+    /**
+     * Set the user token for subsequent requests
+     * This allows you to omit the userToken parameter in other methods
+     *
+     * @param userToken - The user's token
+     */
+    setUserToken(userToken: string): void;
+    /**
+     * Send a chat completion request
+     *
+     * @param userTokenOrMessages - User token string OR array of messages (if user token was set)
+     * @param messagesOrOptions - Array of messages OR chat options (if first param is user token)
+     * @param options - Chat options (only if first two params are provided)
+     * @returns Chat completion response
+     *
+     * @example
+     * ```typescript
+     * // With explicit user token
+     * const response = await tokenKit.chat('user-token', [
+     *   { role: 'user', content: 'What is Token-Kit?' }
+     * ]);
+     *
+     * // With pre-set user token
+     * tokenKit.setUserToken('user-token');
+     * const response = await tokenKit.chat([
+     *   { role: 'user', content: 'What is Token-Kit?' }
+     * ]);
+     *
+     * // With options
+     * const response = await tokenKit.chat('user-token', [
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ], {
+     *   model: 'gpt-4',
+     *   maxTokens: 200,
+     *   temperature: 0.8
+     * });
+     * ```
+     */
+    chat(userTokenOrMessages: string | Message[], messagesOrOptions?: Message[] | ChatOptions, options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Validate a user token and check balance
+     *
+     * @param userToken - User token to validate (optional if already set)
+     * @returns Token validation response with balance and limits
+     *
+     * @example
+     * ```typescript
+     * const validation = await tokenKit.validateToken('user-token');
+     * console.log('Balance:', validation.balance);
+     * console.log('Daily spending:', validation.dailySpending);
+     * ```
+     */
+    validateToken(userToken?: string): Promise<TokenValidationResponse>;
+    /**
+     * Get balance for the current user token
+     *
+     * @param userToken - User token (optional if already set)
+     * @returns Current token balance
+     *
+     * @example
+     * ```typescript
+     * const balance = await tokenKit.getBalance('user-token');
+     * console.log(`You have ${balance} tokens remaining`);
+     * ```
+     */
+    getBalance(userToken?: string): Promise<number>;
+    /**
+     * Get list of available LLM models
+     *
+     * @returns Array of model names
+     *
+     * @example
+     * ```typescript
+     * const models = await tokenKit.getModels();
+     * console.log('Available models:', models);
+     * // ['gpt-3.5-turbo', 'gpt-4', 'gpt-4-turbo']
+     * ```
+     */
+    getModels(): Promise<string[]>;
+    /**
+     * Helper method to create a simple user message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    static user(content: string): Message;
+    /**
+     * Helper method to create a system message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    static system(content: string): Message;
+    /**
+     * Helper method to create an assistant message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    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 };

package/dist/index.js

@@ -0,0 +1,359 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TokenKit: () => TokenKit,
+  TokenKitAPIError: () => TokenKitAPIError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_axios = __toESM(require("axios"));
+
+// src/types.ts
+var TokenKitAPIError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.name = "TokenKitAPIError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+};
+
+// src/client.ts
+var TokenKitClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.client = import_axios.default.create({
+      baseURL: config.baseUrl || "https://api.token-kit.com/api/v1",
+      timeout: config.timeout || 6e4,
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      }
+    });
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        return Promise.reject(this.handleError(error));
+      }
+    );
+  }
+  /**
+   * Send a chat completion request
+   */
+  async chat(userToken, messages, options = {}) {
+    try {
+      const response = await this.client.post("/llm/chat", {
+        userToken,
+        messages,
+        model: options.model,
+        maxTokens: options.maxTokens,
+        temperature: options.temperature
+      });
+      if (!response.data.success || !response.data.data) {
+        throw new TokenKitAPIError(
+          response.data.error?.message || "Chat request failed",
+          response.data.error?.code || "CHAT_ERROR",
+          response.status,
+          response.data.error?.details
+        );
+      }
+      return response.data.data;
+    } catch (error) {
+      if (error instanceof TokenKitAPIError) {
+        throw error;
+      }
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Validate a user token
+   */
+  async validateToken(userToken) {
+    try {
+      const response = await this.client.post(
+        "/tokens/validate",
+        { userToken }
+      );
+      if (!response.data.success || !response.data.data) {
+        throw new TokenKitAPIError(
+          response.data.error?.message || "Token validation failed",
+          response.data.error?.code || "VALIDATION_ERROR",
+          response.status,
+          response.data.error?.details
+        );
+      }
+      return response.data.data;
+    } catch (error) {
+      if (error instanceof TokenKitAPIError) {
+        throw error;
+      }
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Get list of available models
+   */
+  async getModels() {
+    try {
+      const response = await this.client.get("/llm/models");
+      if (!response.data.success || !response.data.data) {
+        throw new TokenKitAPIError(
+          response.data.error?.message || "Failed to fetch models",
+          response.data.error?.code || "MODELS_ERROR",
+          response.status,
+          response.data.error?.details
+        );
+      }
+      return response.data.data.models;
+    } catch (error) {
+      if (error instanceof TokenKitAPIError) {
+        throw error;
+      }
+      throw this.handleError(error);
+    }
+  }
+  /**
+   * Handle axios errors and convert to TokenKitAPIError
+   */
+  handleError(error) {
+    const isAxios = import_axios.default.isAxiosError(error) || typeof error === "object" && error !== null && "isAxiosError" in error;
+    if (isAxios) {
+      const axiosError = error;
+      if (axiosError.code === "ECONNABORTED") {
+        return new TokenKitAPIError(
+          "Request timeout",
+          "TIMEOUT",
+          504
+        );
+      }
+      if (axiosError.code === "ECONNREFUSED" || !axiosError.response) {
+        return new TokenKitAPIError(
+          "Unable to connect to Token-Kit API",
+          "NETWORK_ERROR",
+          503
+        );
+      }
+      if (axiosError.response?.data?.error) {
+        return new TokenKitAPIError(
+          axiosError.response.data.error.message,
+          axiosError.response.data.error.code,
+          axiosError.response.status,
+          axiosError.response.data.error.details
+        );
+      }
+      return new TokenKitAPIError(
+        axiosError.message || "API request failed",
+        "API_ERROR",
+        axiosError.response?.status
+      );
+    }
+    if (error instanceof Error) {
+      return new TokenKitAPIError(
+        error.message,
+        "UNKNOWN_ERROR"
+      );
+    }
+    return new TokenKitAPIError(
+      "An unknown error occurred",
+      "UNKNOWN_ERROR"
+    );
+  }
+};
+
+// src/index.ts
+var TokenKit = class {
+  /**
+   * Create a new TokenKit instance
+   * 
+   * @param config - Configuration options
+   * @param config.apiKey - Your developer API key
+   * @param config.baseUrl - API base URL (optional, defaults to production)
+   * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
+   */
+  constructor(config) {
+    this.userToken = null;
+    this.client = new TokenKitClient(config);
+  }
+  /**
+   * Set the user token for subsequent requests
+   * This allows you to omit the userToken parameter in other methods
+   * 
+   * @param userToken - The user's token
+   */
+  setUserToken(userToken) {
+    this.userToken = userToken;
+  }
+  /**
+   * Send a chat completion request
+   * 
+   * @param userTokenOrMessages - User token string OR array of messages (if user token was set)
+   * @param messagesOrOptions - Array of messages OR chat options (if first param is user token)
+   * @param options - Chat options (only if first two params are provided)
+   * @returns Chat completion response
+   * 
+   * @example
+   * ```typescript
+   * // With explicit user token
+   * const response = await tokenKit.chat('user-token', [
+   *   { role: 'user', content: 'What is Token-Kit?' }
+   * ]);
+   * 
+   * // With pre-set user token
+   * tokenKit.setUserToken('user-token');
+   * const response = await tokenKit.chat([
+   *   { role: 'user', content: 'What is Token-Kit?' }
+   * ]);
+   * 
+   * // With options
+   * const response = await tokenKit.chat('user-token', [
+   *   { role: 'system', content: 'You are a helpful assistant.' },
+   *   { role: 'user', content: 'Hello!' }
+   * ], {
+   *   model: 'gpt-4',
+   *   maxTokens: 200,
+   *   temperature: 0.8
+   * });
+   * ```
+   */
+  async chat(userTokenOrMessages, messagesOrOptions, options) {
+    let userToken;
+    let messages;
+    let chatOptions;
+    if (typeof userTokenOrMessages === "string") {
+      userToken = userTokenOrMessages;
+      messages = messagesOrOptions;
+      chatOptions = options;
+    } else {
+      if (!this.userToken) {
+        throw new Error("User token not set. Call setUserToken() first or pass userToken to chat().");
+      }
+      userToken = this.userToken;
+      messages = userTokenOrMessages;
+      chatOptions = messagesOrOptions;
+    }
+    if (!messages || messages.length === 0) {
+      throw new Error("Messages array cannot be empty");
+    }
+    return this.client.chat(userToken, messages, chatOptions);
+  }
+  /**
+   * Validate a user token and check balance
+   * 
+   * @param userToken - User token to validate (optional if already set)
+   * @returns Token validation response with balance and limits
+   * 
+   * @example
+   * ```typescript
+   * const validation = await tokenKit.validateToken('user-token');
+   * console.log('Balance:', validation.balance);
+   * console.log('Daily spending:', validation.dailySpending);
+   * ```
+   */
+  async validateToken(userToken) {
+    const token = userToken || this.userToken;
+    if (!token) {
+      throw new Error("User token not set. Call setUserToken() first or pass userToken to validateToken().");
+    }
+    return this.client.validateToken(token);
+  }
+  /**
+   * Get balance for the current user token
+   * 
+   * @param userToken - User token (optional if already set)
+   * @returns Current token balance
+   * 
+   * @example
+   * ```typescript
+   * const balance = await tokenKit.getBalance('user-token');
+   * console.log(`You have ${balance} tokens remaining`);
+   * ```
+   */
+  async getBalance(userToken) {
+    const validation = await this.validateToken(userToken);
+    return validation.balance || 0;
+  }
+  /**
+   * Get list of available LLM models
+   * 
+   * @returns Array of model names
+   * 
+   * @example
+   * ```typescript
+   * const models = await tokenKit.getModels();
+   * console.log('Available models:', models);
+   * // ['gpt-3.5-turbo', 'gpt-4', 'gpt-4-turbo']
+   * ```
+   */
+  async getModels() {
+    return this.client.getModels();
+  }
+  /**
+   * Helper method to create a simple user message
+   * 
+   * @param content - Message content
+   * @returns Message object
+   */
+  static user(content) {
+    return { role: "user", content };
+  }
+  /**
+   * Helper method to create a system message
+   * 
+   * @param content - Message content
+   * @returns Message object
+   */
+  static system(content) {
+    return { role: "system", content };
+  }
+  /**
+   * Helper method to create an assistant message
+   * 
+   * @param content - Message content
+   * @returns Message object
+   */
+  static assistant(content) {
+    return { role: "assistant", content };
+  }
+};
+var index_default = TokenKit;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TokenKit,
+  TokenKitAPIError
+});