oblien 1.0.7 → 1.1.1

package/src/credits/index.js

@@ -0,0 +1,299 @@
+/**
+ * Credits Module
+ * Manages credits, quotas, usage tracking, and transactions
+ */
+
+export class OblienCredits {
+    /**
+     * @param {import('../client.js').OblienClient} client - Oblien client instance
+     */
+    constructor(client) {
+        if (!client) {
+            throw new Error('Oblien client is required');
+        }
+
+        this.client = client;
+    }
+
+    // =============================================================================
+    // Balance Management
+    // =============================================================================
+
+    /**
+     * Get client's total credit balance
+     * @returns {Promise<number>} Current credit balance
+     */
+    async getBalance() {
+        const response = await this.client.get('credits/balance');
+        return response.balance;
+    }
+
+    /**
+     * Add credits to client (internal use - requires admin permissions)
+     * @param {number} amount - Amount of credits to add
+     * @param {string} [reason] - Reason for adding credits
+     * @param {Object} [metadata] - Additional metadata
+     * @returns {Promise<Object>} Result with new balance
+     */
+    async addCredits(amount, reason = 'manual', metadata = {}) {
+        const response = await this.client.post('credits/add', {
+            amount,
+            reason,
+            metadata
+        });
+        return response;
+    }
+
+    // =============================================================================
+    // Quota Management
+    // =============================================================================
+
+    /**
+     * Get all namespace quotas with pagination and filtering
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Max results (default: 100, max: 500)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.after] - Cursor for pagination (format: "namespace:service")
+     * @param {string} [options.search] - Search query
+     * @param {string} [options.status] - Filter by status: 'active', 'warning', 'exceeded'
+     * @returns {Promise<Object>} Namespaces with quotas and pagination info
+     */
+    async getNamespaceQuotas(options = {}) {
+        const response = await this.client.get('credits/namespaces', options);
+        return response;
+    }
+
+    /**
+     * Get detailed namespace quota information
+     * @param {string} namespace - Namespace slug or ID
+     * @param {Object} [options] - Query options
+     * @param {number} [options.days] - Number of days for stats (default: 7, max: 90)
+     * @returns {Promise<Object>} Namespace details with quotas, usage, and transactions
+     */
+    async getNamespaceDetails(namespace, options = {}) {
+        const response = await this.client.get(`credits/namespaces/${namespace}`, options);
+        return response;
+    }
+
+    /**
+     * Set quota for a namespace and service
+     * @param {Object} options - Quota options
+     * @param {string} options.namespace - Namespace slug
+     * @param {string} options.service - Service name (e.g., 'ai', 'deployment', 'sandbox')
+     * @param {number} options.quotaLimit - Quota limit (null or 0 for unlimited)
+     * @param {string} [options.period] - Quota period: 'daily', 'monthly', 'unlimited'
+     * @returns {Promise<Object>} Created/updated quota
+     */
+    async setQuota(options) {
+        if (!options.namespace || !options.service) {
+            throw new Error('namespace and service are required');
+        }
+
+        if (options.quotaLimit === undefined) {
+            throw new Error('quotaLimit is required');
+        }
+
+        const response = await this.client.post('credits/namespace-quota', {
+            namespace: options.namespace,
+            service: options.service,
+            quotaLimit: options.quotaLimit,
+            period: options.period || 'unlimited'
+        });
+
+        return response;
+    }
+
+    /**
+     * Reset namespace quota (e.g., for monthly reset)
+     * @param {string} namespace - Namespace slug
+     * @param {string} service - Service name
+     * @returns {Promise<Object>} Reset result
+     */
+    async resetQuota(namespace, service) {
+        if (!namespace || !service) {
+            throw new Error('namespace and service are required');
+        }
+
+        const response = await this.client.post('credits/reset-quota', {
+            namespace,
+            service
+        });
+
+        return response;
+    }
+
+    // =============================================================================
+    // Usage History & Transactions
+    // =============================================================================
+
+    /**
+     * Get credit usage history with filtering and pagination
+     * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {string} [options.endUserId] - Filter by end user ID
+     * @param {string} [options.service] - Filter by service
+     * @param {string} [options.type] - Filter by type: 'deduction', 'addition', 'refund', 'adjustment'
+     * @param {string} [options.startDate] - Start date (ISO string)
+     * @param {string} [options.endDate] - End date (ISO string)
+     * @param {number} [options.limit] - Max results (default: 50)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {string} [options.after] - Cursor for pagination (timestamp)
+     * @param {number} [options.afterId] - Cursor ID for pagination
+     * @returns {Promise<Object>} History with transactions and pagination
+     */
+    async getHistory(options = {}) {
+        const response = await this.client.get('credits/history', options);
+        return response;
+    }
+
+    /**
+     * Get available filter options for history
+     * @returns {Promise<Object>} Available namespaces and services
+     */
+    async getHistoryFilters() {
+        const response = await this.client.get('credits/history/filters');
+        return response;
+    }
+
+    /**
+     * Get usage summary by namespace/service
+     * @param {Object} [options] - Query options
+     * @param {string} [options.namespace] - Filter by namespace
+     * @param {number} [options.days] - Number of days to look back (default: 30)
+     * @param {number} [options.limit] - Max results (default: 50, max: 500)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {number} [options.after] - Cursor for pagination (total_spent value)
+     * @returns {Promise<Object>} Summary with aggregated usage
+     */
+    async getSummary(options = {}) {
+        const response = await this.client.get('credits/summary', options);
+        return response;
+    }
+
+    /**
+     * Get daily usage statistics (for charts)
+     * @param {Object} [options] - Query options
+     * @param {number} [options.days] - Number of days (default: 7)
+     * @returns {Promise<Object>} Daily usage statistics
+     */
+    async getUsageStats(options = {}) {
+        const response = await this.client.get('credits/usage-stats', options);
+        return response;
+    }
+
+    // =============================================================================
+    // Pricing & Packages
+    // =============================================================================
+
+    /**
+     * Get available credit packages
+     * @returns {Promise<Array>} Array of credit packages
+     */
+    async getPackages() {
+        const response = await this.client.get('credits/packages');
+        return response.packages || response.data || response;
+    }
+
+    /**
+     * Get pricing information and limits
+     * @returns {Promise<Object>} Pricing info with rates and limits
+     */
+    async getPricingInfo() {
+        const response = await this.client.get('credits/pricing-info');
+        return response;
+    }
+
+    /**
+     * Calculate credits from money or vice versa
+     * @param {Object} options - Calculation options
+     * @param {string} [options.packageId] - Package ID to calculate
+     * @param {number} [options.amount] - Money amount to convert to credits
+     * @param {number} [options.credits] - Credits to convert to money
+     * @returns {Promise<Object>} Calculation result with amount and credits
+     */
+    async calculateCost(options) {
+        if (!options.packageId && !options.amount && !options.credits) {
+            throw new Error('Must provide either packageId, amount, or credits');
+        }
+
+        const response = await this.client.post('credits/calculate-cost', options);
+        return response;
+    }
+
+    /**
+     * Calculate credits for a given amount (preview)
+     * @param {number} amount - Money amount
+     * @returns {Promise<Object>} Credits calculation
+     */
+    async calculateCredits(amount) {
+        const response = await this.client.get('credits/calculate', { amount });
+        return response;
+    }
+
+    // =============================================================================
+    // Purchase Management
+    // =============================================================================
+
+    /**
+     * Create Stripe checkout to purchase credits
+     * @param {Object} options - Purchase options
+     * @param {string} [options.packageId] - Package ID to purchase
+     * @param {number} [options.amount] - Custom amount to purchase
+     * @param {Object} [options.metadata] - Additional metadata
+     * @returns {Promise<Object>} Checkout session with URL
+     */
+    async createCheckout(options) {
+        if (!options.packageId && !options.amount) {
+            throw new Error('Must provide either packageId or amount');
+        }
+
+        const response = await this.client.post('credits/purchase', options);
+        return response;
+    }
+
+    /**
+     * Get purchase history
+     * @param {Object} [options] - Query options
+     * @param {number} [options.limit] - Max results (default: 50, max: 100)
+     * @param {number} [options.offset] - Offset for pagination
+     * @param {boolean} [options.light] - If true, returns basic data only (faster)
+     * @returns {Promise<Object>} Purchase history with pagination
+     */
+    async getPurchaseHistory(options = {}) {
+        const response = await this.client.get('credits/purchases', options);
+        return response;
+    }
+
+    /**
+     * Get single purchase details
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Purchase details
+     */
+    async getPurchaseDetails(purchaseId) {
+        const response = await this.client.get(`credits/purchases/${purchaseId}`);
+        return response;
+    }
+
+    /**
+     * Get Stripe checkout session URL for pending purchase
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Session with checkout URL
+     */
+    async getPurchaseSession(purchaseId) {
+        const response = await this.client.get(`credits/purchases/${purchaseId}/session`);
+        return response;
+    }
+
+    /**
+     * Cancel a pending purchase
+     * @param {string} purchaseId - Purchase ID
+     * @returns {Promise<Object>} Cancellation result
+     */
+    async cancelPurchase(purchaseId) {
+        const response = await this.client.post(`credits/purchases/${purchaseId}/cancel`);
+        return response;
+    }
+}
+
+export default OblienCredits;
+

package/src/icons/index.js

@@ -0,0 +1,185 @@
+/**
+ * Oblien Icons Module
+ * Search and fetch icons, images, and videos
+ */
+
+export class OblienIcons {
+    constructor(client) {
+        if (!client) throw new Error('Oblien client is required');
+        this.client = client;
+    }
+
+    /**
+     * Search for icons using semantic search
+     * 
+     * @param {string} query - Search query
+     * @param {Object} options - Search options
+     * @param {number} options.offset - Pagination offset (default: 0)
+     * @param {number} options.limit - Number of results (default: 100)
+     * @returns {Promise<Object>} Search results with pagination info
+     * 
+     * @example
+     * const results = await icons.search('home', { limit: 50 });
+     * // Returns:
+     * // {
+     * //   results: [
+     * //     {
+     * //       url: 'https://cdn.oblien.com/static/png-icons/...',
+     * //       filename: 'home-outline.png',
+     * //       name: 'home',
+     * //       description: 'home',
+     * //       style: 'Outline',
+     * //       score: 0.95,
+     * //       success: true
+     * //     }
+     * //   ],
+     * //   hasMore: true,
+     * //   offset: 50,
+     * //   total: 245
+     * // }
+     */
+    async search(query, options = {}) {
+        if (!query || typeof query !== 'string') {
+            throw new Error('Query must be a non-empty string');
+        }
+
+        const { offset = 0, limit = 100 } = options;
+
+        return this.client.post('icons/search-icons', {
+            query: query.trim(),
+            offset,
+            limit
+        });
+    }
+
+    /**
+     * Fetch multiple items (icons, images, videos) with semantic matching
+     * 
+     * @param {Array<Object>} items - Array of items to fetch
+     * @param {string} items[].type - Type: 'icon', 'image', or 'video'
+     * @param {string} items[].description - Description for semantic matching
+     * @param {boolean} items[].is_vector - Whether the item is a vector (optional)
+     * @param {string} items[].variant - Variant type (optional, for images/videos)
+     * @returns {Promise<Array>} Array of fetched items with URLs
+     * 
+     * @example
+     * const items = await icons.fetch([
+     *   { type: 'icon', description: 'user profile' },
+     *   { type: 'icon', description: 'settings gear' },
+     *   { type: 'image', description: 'mountain landscape' },
+     *   { type: 'video', description: 'ocean waves' }
+     * ]);
+     * 
+     * // Returns:
+     * // [
+     * //   {
+     * //     url: 'https://cdn.oblien.com/static/icons/...',
+     * //     description: 'user profile',
+     * //     style: 'Outline',
+     * //     success: true
+     * //   },
+     * //   {
+     * //     url: 'https://cdn.oblien.com/static/assets/...',
+     * //     type: 'image',
+     * //     description: 'mountain landscape',
+     * //     variant: 'regular',
+     * //     success: true
+     * //   }
+     * // ]
+     */
+    async fetch(items) {
+        if (!Array.isArray(items) || items.length === 0) {
+            throw new Error('Items must be a non-empty array');
+        }
+
+        // Validate items
+        for (const item of items) {
+            if (!item.type || !['icon', 'image', 'video'].includes(item.type)) {
+                throw new Error('Each item must have a valid type: icon, image, or video');
+            }
+            if (!item.description || typeof item.description !== 'string') {
+                throw new Error('Each item must have a description string');
+            }
+        }
+
+        return this.client.post('icons/fetch', { data: items });
+    }
+
+    /**
+     * Fetch a single icon
+     * Convenience method for fetching one icon
+     * 
+     * @param {string} description - Icon description
+     * @returns {Promise<Object>} Icon object with URL
+     * 
+     * @example
+     * const icon = await icons.fetchIcon('home');
+     * // Returns: { url: '...', description: 'home', style: 'Outline', success: true }
+     */
+    async fetchIcon(description) {
+        if (!description || typeof description !== 'string') {
+            throw new Error('Description must be a non-empty string');
+        }
+
+        const result = await this.fetch([{ type: 'icon', description }]);
+        return result[0] || null;
+    }
+
+    /**
+     * Fetch multiple icons at once
+     * Convenience method for fetching multiple icons
+     * 
+     * @param {Array<string>} descriptions - Array of icon descriptions
+     * @returns {Promise<Array>} Array of icon objects
+     * 
+     * @example
+     * const icons = await icons.fetchIcons(['home', 'settings', 'user']);
+     * // Returns: [{ url: '...', description: 'home', ... }, ...]
+     */
+    async fetchIcons(descriptions) {
+        if (!Array.isArray(descriptions) || descriptions.length === 0) {
+            throw new Error('Descriptions must be a non-empty array');
+        }
+
+        const items = descriptions.map(desc => ({ type: 'icon', description: desc }));
+        return this.fetch(items);
+    }
+
+    /**
+     * Search icons with pagination helper
+     * Automatically handles pagination and returns all results
+     * 
+     * @param {string} query - Search query
+     * @param {Object} options - Search options
+     * @param {number} options.maxResults - Maximum results to fetch (default: 500)
+     * @param {number} options.batchSize - Results per batch (default: 100)
+     * @returns {Promise<Array>} All matching icons
+     * 
+     * @example
+     * const allIcons = await icons.searchAll('home', { maxResults: 200 });
+     * // Returns: [{ url: '...', name: 'home', ... }, ...]
+     */
+    async searchAll(query, options = {}) {
+        const { maxResults = 500, batchSize = 100 } = options;
+        const allResults = [];
+        let offset = 0;
+        let hasMore = true;
+
+        while (hasMore && allResults.length < maxResults) {
+            const response = await this.search(query, {
+                offset,
+                limit: Math.min(batchSize, maxResults - allResults.length)
+            });
+
+            if (response.results && response.results.length > 0) {
+                allResults.push(...response.results);
+            }
+
+            hasMore = response.hasMore && allResults.length < maxResults;
+            offset = response.offset;
+        }
+
+        return allResults;
+    }
+}
+