@vargai/sdk 0.1.1

package/lib/higgsfield/README.md

@@ -0,0 +1,273 @@
+# Higgsfield API Client
+
+HTTP-based client for the Higgsfield AI platform, implementing the asynchronous queue pattern for content generation.
+
+## Overview
+
+The Higgsfield API uses an asynchronous request-response pattern where requests enter a queue and process in the background. This implementation provides:
+
+- Direct HTTP requests (no external client library)
+- Queue management (submit, status check, cancel)
+- Automatic polling with status updates
+- Webhook support for async notifications
+- Model-specific clients (Soul, etc.)
+
+## Installation
+
+Set your Higgsfield API credentials as environment variables:
+
+```bash
+export HIGGSFIELD_API_KEY="your-api-key"
+export HIGGSFIELD_SECRET="your-api-secret"
+# or
+export HF_API_KEY="your-api-key"
+export HF_API_SECRET="your-api-secret"
+```
+
+## Usage
+
+### Soul Image Generation
+
+```typescript
+import { generateSoul, SoulSize, SoulQuality } from "./lib/higgsfield/soul";
+
+// Simple generation
+const result = await generateSoul({
+  prompt: "beautiful sunset over mountains",
+  width_and_height: SoulSize.PORTRAIT_1152x2048,
+  quality: SoulQuality.HD,
+  batch_size: 1,
+  enhance_prompt: false,
+});
+
+console.log(result.images[0].url);
+```
+
+### With Style
+
+```typescript
+import { generateSoul, listSoulStyles } from "./lib/higgsfield/soul";
+
+// List available styles
+const styles = await listSoulStyles();
+console.log(styles);
+
+// Generate with specific style
+const result = await generateSoul({
+  prompt: "portrait of a woman",
+  style_id: "style-id-from-list",
+  quality: "1080p",
+});
+```
+
+### With Webhook
+
+```typescript
+const result = await generateSoul(
+  {
+    prompt: "landscape painting",
+  },
+  {
+    webhook: "https://your-webhook.url/endpoint",
+  },
+);
+
+// Returns immediately with request info
+console.log(result.request_id);
+// Your webhook will receive the result when ready
+```
+
+### Manual Queue Management
+
+```typescript
+import { SoulClient } from "./lib/higgsfield/soul";
+
+const client = new SoulClient();
+
+// Submit request
+const request = await client.submitRequest("soul", {
+  prompt: "beautiful landscape",
+  quality: "1080p",
+});
+
+console.log(request.request_id);
+
+// Check status manually
+const status = await client.getStatus(request.request_id);
+console.log(status.status); // "queued", "in_progress", "completed", etc.
+
+// Cancel if still queued
+if (status.status === "queued") {
+  await client.cancelRequest(request.request_id);
+}
+
+// Or wait for completion
+const result = await client.waitForCompletion(request.request_id, {
+  pollingInterval: 2000, // 2 seconds
+  maxWaitTime: 300000, // 5 minutes
+  onUpdate: (status) => {
+    console.log(`Status: ${status.status}`);
+  },
+});
+```
+
+### Using the Base Client
+
+```typescript
+import HiggsfieldClient from "./lib/higgsfield/index";
+
+const client = new HiggsfieldClient({
+  apiKey: "your-api-key",
+  apiSecret: "your-api-secret",
+});
+
+// Works with any Higgsfield model
+const result = await client.generate("model-id", {
+  // model-specific params
+});
+```
+
+## CLI Usage
+
+### Soul Commands
+
+```bash
+# Generate image
+bun run lib/higgsfield/soul.ts generate "beautiful sunset"
+
+# Generate with style
+bun run lib/higgsfield/soul.ts generate "portrait" "style-id-123"
+
+# List available styles
+bun run lib/higgsfield/soul.ts list_styles
+
+# Check request status
+bun run lib/higgsfield/soul.ts status "request-id"
+
+# Cancel pending request
+bun run lib/higgsfield/soul.ts cancel "request-id"
+```
+
+### Legacy Commands (backward compatible)
+
+```bash
+bun run lib/higgsfield.ts generate_soul "beautiful landscape"
+bun run lib/higgsfield.ts list_styles
+```
+
+## API Reference
+
+### Request Statuses
+
+| Status | Description |
+|--------|-------------|
+| `queued` | Request is waiting in queue |
+| `in_progress` | Generation is actively processing |
+| `nsfw` | Content failed moderation (credits refunded) |
+| `failed` | Generation failed (credits refunded) |
+| `completed` | Generation finished successfully |
+| `canceled` | Request was canceled |
+
+### Soul Parameters
+
+```typescript
+interface SoulGenerationParams {
+  prompt: string; // Required
+  width_and_height?: string; // e.g., "1152x2048"
+  quality?: "720p" | "1080p";
+  style_id?: string; // From listSoulStyles()
+  batch_size?: 1 | 4;
+  enhance_prompt?: boolean;
+  seed?: number;
+  style_strength?: number;
+  image_reference?: string; // URL
+  custom_reference_id?: string;
+  custom_reference_strength?: number;
+}
+```
+
+### Soul Size Options
+
+```typescript
+import { SoulSize } from "./lib/higgsfield/soul";
+
+SoulSize.PORTRAIT_1152x2048
+SoulSize.PORTRAIT_2048x1152
+SoulSize.SQUARE_2048x2048
+SoulSize.LANDSCAPE_1536x2048
+SoulSize.LANDSCAPE_2016x1344
+```
+
+### Quality Options
+
+```typescript
+import { SoulQuality } from "./lib/higgsfield/soul";
+
+SoulQuality.SD // "720p"
+SoulQuality.HD // "1080p"
+```
+
+## Webhook Integration
+
+When you provide a webhook URL, the API will send a POST request to your endpoint when generation completes:
+
+```typescript
+// Your webhook endpoint receives:
+{
+  "status": "completed",
+  "request_id": "uuid",
+  "status_url": "https://...",
+  "cancel_url": "https://...",
+  "images": [{ "url": "https://..." }]
+}
+```
+
+Webhook retries:
+- Retries for up to 2 hours
+- Continues until your endpoint returns 2xx status
+- Implement idempotency using `request_id`
+
+## Best Practices
+
+1. **Store Request IDs**: Save `request_id` to retrieve results later
+2. **Handle All Statuses**: Check for `completed`, `failed`, `nsfw`, and `canceled`
+3. **Use Webhooks for Long Tasks**: Avoid keeping connections open
+4. **Implement Idempotency**: Handle duplicate webhook deliveries gracefully
+5. **Set Reasonable Timeouts**: Default is 5 minutes, adjust as needed
+6. **Cancel Unused Requests**: Free up queue slots when possible
+
+## Migration from Client Library
+
+If you're migrating from `@higgsfield/client`:
+
+### Before
+```typescript
+import { HiggsfieldClient } from "@higgsfield/client";
+
+const client = new HiggsfieldClient({ apiKey, apiSecret });
+const jobSet = await client.generate("/v1/text2image/soul", params);
+```
+
+### After
+```typescript
+import { generateSoul } from "./lib/higgsfield/soul";
+
+const result = await generateSoul(params);
+```
+
+The new API returns the same data structure but uses native HTTP requests instead of a client library.
+
+## Architecture
+
+```
+lib/higgsfield/
+├── index.ts        # Base HiggsfieldClient class
+├── soul.ts         # Soul-specific API
+└── README.md       # This file
+
+lib/higgsfield.ts   # Backward-compatible wrapper
+```
+
+Each model can have its own file with specialized methods while sharing the base queue management from `index.ts`.
+
+

package/lib/higgsfield/example.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env bun
+/**
+ * Example usage of the new Higgsfield HTTP API
+ */
+
+import {
+  generateSoul,
+  listSoulStyles,
+  SoulClient,
+  SoulSize,
+  SoulQuality,
+  BatchSize,
+} from "./soul";
+
+// Example 1: Simple generation
+async function simpleGeneration() {
+  console.log("=== Example 1: Simple Generation ===\n");
+
+  const result = await generateSoul({
+    prompt: "a serene mountain landscape at sunset",
+    width_and_height: SoulSize.LANDSCAPE_1536x2048,
+    quality: SoulQuality.HD,
+    batch_size: BatchSize.SINGLE,
+  });
+
+  if (result.status === "completed" && result.images) {
+    console.log("✓ Generation successful!");
+    console.log(`Image URL: ${result.images[0].url}`);
+  } else {
+    console.log(`✗ Generation ${result.status}`);
+  }
+}
+
+// Example 2: List and use styles
+async function generationWithStyle() {
+  console.log("\n=== Example 2: Generation with Style ===\n");
+
+  // First, list available styles
+  const styles = await listSoulStyles();
+  console.log(`Found ${styles.length} available styles`);
+
+  if (styles.length > 0) {
+    const firstStyle = styles[0];
+    console.log(`Using style: ${firstStyle.name} (${firstStyle.id})`);
+
+    const result = await generateSoul({
+      prompt: "portrait of a wise old wizard",
+      style_id: firstStyle.id,
+      quality: SoulQuality.HD,
+    });
+
+    if (result.status === "completed" && result.images) {
+      console.log("✓ Generation with style successful!");
+      console.log(`Image URL: ${result.images[0].url}`);
+    }
+  }
+}
+
+// Example 3: Manual queue management
+async function manualQueueManagement() {
+  console.log("\n=== Example 3: Manual Queue Management ===\n");
+
+  const client = new SoulClient();
+
+  // Submit request
+  const request = await client.submitRequest("soul", {
+    prompt: "futuristic city skyline",
+    quality: "1080p",
+  });
+
+  console.log(`Request submitted: ${request.request_id}`);
+  console.log(`Status: ${request.status}`);
+
+  // Poll for status updates
+  const result = await client.waitForCompletion(request.request_id, {
+    pollingInterval: 2000,
+    maxWaitTime: 300000,
+    onUpdate: (status) => {
+      console.log(`  → ${status.status}`);
+    },
+  });
+
+  if (result.status === "completed" && result.images) {
+    console.log("✓ Generation complete!");
+    console.log(`Image URL: ${result.images[0].url}`);
+  }
+}
+
+// Example 4: With webhook (for production)
+async function generationWithWebhook() {
+  console.log("\n=== Example 4: Generation with Webhook ===\n");
+
+  const result = await generateSoul(
+    {
+      prompt: "abstract art with vibrant colors",
+      quality: SoulQuality.HD,
+    },
+    {
+      webhook: "https://your-webhook.url/higgsfield",
+    },
+  );
+
+  console.log(
+    "Request submitted with webhook - will receive results at webhook URL",
+  );
+  console.log(`Request ID: ${result.request_id}`);
+  console.log(`Status URL: ${result.status_url}`);
+}
+
+// Example 5: Batch generation
+async function batchGeneration() {
+  console.log("\n=== Example 5: Batch Generation ===\n");
+
+  const result = await generateSoul({
+    prompt: "cute cartoon character designs",
+    batch_size: BatchSize.FOUR,
+    quality: SoulQuality.HD,
+  });
+
+  if (result.status === "completed" && result.images) {
+    console.log(`✓ Generated ${result.images.length} images`);
+    for (const [index, image] of result.images.entries()) {
+      console.log(`  ${index + 1}. ${image.url}`);
+    }
+  }
+}
+
+// Example 6: Error handling
+async function errorHandling() {
+  console.log("\n=== Example 6: Error Handling ===\n");
+
+  const client = new SoulClient();
+
+  try {
+    const result = await client.generateSoul({
+      prompt: "test prompt",
+      quality: SoulQuality.HD,
+    });
+
+    switch (result.status) {
+      case "completed":
+        console.log("✓ Success!");
+        break;
+      case "failed":
+        console.log(`✗ Failed: ${result.error}`);
+        break;
+      case "nsfw":
+        console.log("✗ Content flagged as NSFW (credits refunded)");
+        break;
+      case "canceled":
+        console.log("✗ Request was canceled");
+        break;
+      default:
+        console.log(`? Unexpected status: ${result.status}`);
+    }
+  } catch (error) {
+    console.error("Error during generation:", error);
+  }
+}
+
+// Run examples
+if (import.meta.main) {
+  const example = process.argv[2];
+
+  try {
+    switch (example) {
+      case "1":
+      case "simple":
+        await simpleGeneration();
+        break;
+      case "2":
+      case "style":
+        await generationWithStyle();
+        break;
+      case "3":
+      case "queue":
+        await manualQueueManagement();
+        break;
+      case "4":
+      case "webhook":
+        await generationWithWebhook();
+        break;
+      case "5":
+      case "batch":
+        await batchGeneration();
+        break;
+      case "6":
+      case "error":
+        await errorHandling();
+        break;
+      case "all":
+        // Run all examples (except webhook)
+        await simpleGeneration();
+        await generationWithStyle();
+        await manualQueueManagement();
+        await batchGeneration();
+        await errorHandling();
+        break;
+      default:
+        console.log(`
+Higgsfield API Examples
+
+Usage:
+  bun run lib/higgsfield/example.ts <example>
+
+Available examples:
+  1, simple     - Simple generation
+  2, style      - Generation with style
+  3, queue      - Manual queue management
+  4, webhook    - Generation with webhook
+  5, batch      - Batch generation (4 images)
+  6, error      - Error handling
+  all           - Run all examples
+
+Examples:
+  bun run lib/higgsfield/example.ts simple
+  bun run lib/higgsfield/example.ts style
+  bun run lib/higgsfield/example.ts all
+        `);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error("\nExample failed:", error);
+    process.exit(1);
+  }
+}
+
+