alexa-ai 2.1.1 → 2.2.1

package/src/AlexaAI.js

@@ -17,6 +17,7 @@ const IdentityResolver = require('./services/IdentityResolver');
 const TriggerDetector = require('./services/TriggerDetector');
 const ImageDescriber = require('./services/ImageDescriber');
 const WebAnswer = require('./services/WebAnswer');
+const WebSearch = require('./services/WebSearch');
 const StreamParser = require('./core/StreamParser');
 const JidParser = require('./utils/JidParser');
 const Media = require('./utils/Media');
@@ -69,6 +70,7 @@ class AlexaAI {
 
         this.prompts = new PromptBuilder(this.config);
         this.vision = new ImageDescriber(this.client, this.config);
+        this.webSearch = new WebSearch(this.config);
 
         // Persona-aware guards (renaming the assistant renames these too).
         this.identityGuard = new IdentityGuard({
@@ -594,27 +596,35 @@ class AlexaAI {
     /**
      * Text-to-image.
      *
-     * Two routes, tried in order:
+     * Three routes, tried in order:
      *
-     *   1. `POST /api/text2img` — the classic public API. Fast and returns a
-     *      plain `output_url`, but it is a PAID endpoint: anonymous `tryit-…`
-     *      keys get `{"status": "Out of API credits"}` / "try it exceeded".
-     *   2. The in-chat image tool — the same `generate_image` function call the
-     *      deepai.org web client sends when you press "Create image". This
-     *      works on free chat keys and answers with a `generated_image` packet
-     *      carrying a `share_url`.
+     *   1. `POST /api/text2img` — the classic public API, returns
+     *      `share_url` / `output_url`. With a Pro key this always works.
+     *      With an anonymous `tryit-…` key the request is automatically sent
+     *      in the exact browser shape (`generation_source=chat` + size +
+     *      `quality=true`), because a bare `{ text }` form is refused with
+     *      "Please try this model on deepai.org". Anonymous keys are also
+     *      single-use, so a fresh one is minted per request.
+     *   2. Anonymous browser-style retry — when a registered (non-Pro) key
+     *      is refused with 402 "Pro members in good standing", the engine
+     *      retries once with a fresh anonymous key. Disable with
+     *      `{ noAnonymousFallback: true }`.
+     *   3. The legacy in-chat image tool — a `generate_image` function-call
+     *      message sent to the chat endpoint; kept for model versions that
+     *      still honor it.
      *
-     * Either way the result is normalised to `{ ok, url, id, error, via }`.
-     * Every failure is returned, never thrown, so a bot command can simply
-     * check `result.ok`.
+     * Either way the result is normalised to `{ ok, url, id, error, via }`
+     * (`via` is 'api' | 'anonymous' | 'chat'). Every failure is returned,
+     * never thrown, so a bot command can simply check `result.ok`.
      *
      * @param {string} prompt
      * @param {object} [opts]
-     * @param {string} [opts.aspectRatio='1:1']   in-chat tool only ('1:1', '16:9', '9:16'…)
+     * @param {string} [opts.aspectRatio='1:1']   '1:1', '16:9', '9:16', '4:3', '3:4'
      * @param {number} [opts.width] / [opts.height]  /api/text2img only
-     * @param {string} [opts.image_generator_version]  /api/text2img only
+     * @param {string} [opts.image_generator_version]  /api/text2img only ('hd', 'standard', 'genius')
      * @param {boolean} [opts.chatToolOnly]     skip /api/text2img
      * @param {boolean} [opts.apiOnly]          skip the in-chat tool
+     * @param {boolean} [opts.noAnonymousFallback]  skip route 2
      * @param {AbortSignal} [opts.signal]
      * @returns {Promise<{ok:boolean, url:string|null, id:string|null, error:string|null, message?:string, via:string|null, raw?:any}>}
      */
@@ -623,25 +633,52 @@ class AlexaAI {
         if (!text) {
             return { ok: false, url: null, id: null, error: 'VALIDATION_ERROR', message: 'generateImage(): prompt is required', via: null };
         }
-        const { aspectRatio, chatToolOnly, apiOnly, signal, ...apiFields } = opts || {};
+        const { aspectRatio, chatToolOnly, apiOnly, noAnonymousFallback, signal, ...apiFields } = opts || {};
         const errors = [];
+        let quotaRefused = false;
 
         // ---- 1. classic /api/text2img -------------------------------------
+        // Anonymous keys require the browser dialect (generation_source +
+        // size/quality fields).
         if (!chatToolOnly) {
             try {
-                const data = await this.client.text2img(text, apiFields, { signal });
+                const extra = this.client.usingTryItKey
+                    ? AlexaAI._browserImageFields(aspectRatio || '1:1', apiFields)
+                    : apiFields;
+                const data = await this.client.text2img(text, extra, { signal });
                 const url = AlexaAI._outputUrl(data);
                 if (url) return { ok: true, url, id: data.id || null, error: null, via: 'api', raw: data };
                 errors.push('text2img: no output_url in response');
             } catch (err) {
                 errors.push(`text2img: ${err.message}`);
+                if (err instanceof QuotaExceededError) quotaRefused = true;
                 if (err.code === 'ABORTED') {
                     return { ok: false, url: null, id: null, error: 'ABORTED', message: err.message, via: null };
                 }
             }
         }
 
-        // ---- 2. the chat image tool (works on free chat keys) ---------------
+        // ---- 2. anonymous browser-style retry ------------------------------
+        // A registered key without Pro gets 402 "APIs are only available for
+        // Pro members in good standing"; retry once with a fresh anonymous
+        // key in the full browser shape.
+        if (quotaRefused && !noAnonymousFallback && !this.client.usingTryItKey) {
+            try {
+                const extra = AlexaAI._browserImageFields(aspectRatio || '1:1', apiFields);
+                const data = await this.client.runApiWithTryItKey(
+                    this.client.config.imageModel || 'text2img',
+                    { text, ...extra },
+                    { signal }
+                );
+                const url = AlexaAI._outputUrl(data);
+                if (url) return { ok: true, url, id: data.id || null, error: null, via: 'anonymous', raw: data };
+                errors.push('anonymous text2img: no output_url in response');
+            } catch (err) {
+                errors.push(`anonymous text2img: ${err.message}`);
+            }
+        }
+
+        // ---- 3. the chat image tool (legacy; model-side tool) --------------
         if (!apiOnly) {
             try {
                 const answer = await this.client.chatDetailed(
@@ -664,12 +701,41 @@ class AlexaAI {
             ok: false,
             url: null,
             id: null,
-            error: /credits|exceeded|paid|api-key|api key/i.test(message) ? 'DEEPAI_QUOTA_EXCEEDED' : 'IMAGE_FAILED',
+            error: quotaRefused || /credits|exceeded|paid|pro members|api-key|api key/i.test(message)
+                ? 'DEEPAI_QUOTA_EXCEEDED'
+                : 'IMAGE_FAILED',
             message,
             via: null,
         };
     }
 
+    /**
+     * Extra form fields required for anonymous image generation: the aspect
+     * ratio is translated to pixel sizes, generation runs in "hd" quality,
+     * and the request is tagged generation_source=chat.
+     *
+     * @param {string} aspectRatio '1:1' | '16:9' | '9:16' | '4:3' | '3:4'
+     * @param {object} [overrides] explicit width/height/image_generator_version win
+     * @private
+     */
+    static _browserImageFields(aspectRatio, overrides = {}) {
+        const map = {
+            '16:9': [832, 448],
+            '4:3': [768, 576],
+            '1:1': [640, 640],
+            '3:4': [576, 768],
+            '9:16': [448, 832],
+        };
+        const [width, height] = map[String(aspectRatio || '1:1')] || map['1:1'];
+        return {
+            generation_source: 'chat',
+            width: overrides.width ?? width,
+            height: overrides.height ?? height,
+            image_generator_version: overrides.image_generator_version ?? 'hd',
+            quality: 'true',
+        };
+    }
+
     /**
      * Prompt-driven image edit (`POST /api/image-editor`).
      * `image` may be a Buffer, base64, data URI, URL or `{ buffer | url }`.
@@ -785,25 +851,35 @@ class AlexaAI {
      * One-off, stateless web research request — for "search the web for X"
      * commands that must not touch anyone's memory.
      *
-     * By default the answer is long-form: an intro, three to five `*Heading:*`
-     * sections with numbered `*Headline*: detail` points (about 300–450
-     * words), followed by one `*Sources:*` block. Sources come from DeepAI's
-     * web-result packet when the model sends one, and are otherwise lifted
-     * out of the "Sources:" list the model writes — either way they are
-     * returned in `sources` and rendered exactly once in `text`.
+     * HOW IT WORKS
+     * ------------
+     * 1. The engine searches the web itself (`WebSearch`: DuckDuckGo, Bing
+     *    News, Google News, Wikipedia — no API key needed) and collects real
+     *    pages with titles, snippets and dates.
+     * 2. Those results go to the model as numbered material. The model writes
+     *    the report from them and cites result numbers; it is told never to
+     *    write a URL.
+     * 3. The `*Sources:*` block is built from the search results only —
+     *    cited ones first. A URL the model wrote itself is never shown.
      *
-     * Small models sometimes ignore the layout and answer in a sentence. When
-     * a long-form answer comes back under `minWords`, one follow-up turn asks
-     * the model to rewrite it in full; the longer of the two replies wins.
+     * When the search returns nothing (offline host, all providers blocked)
+     * the request falls back to DeepAI's server-side web access, which is
+     * unreliable on free models: it may skip the search and invent pages.
+     * `grounded` in the result tells you which path answered.
      *
-     * The persona still applies (WhatsApp formatting, no renaming of the
-     * assistant), but third-party vendor names in the research itself are
-     * kept, and the identity/memory guards run without a user context, so
-     * this is safe to call with no jid at all.
+     * Default output is long-form: an intro, three to five `*Heading:*`
+     * sections with numbered `*Headline*: detail` points (about 300–450
+     * words), then one `*Sources:*` block. A long-form reply under `minWords`
+     * is retried once; the longer reply wins.
      *
      * @param {string} query
      * @param {object} [opts]
      * @param {'long'|'short'} [opts.detail='long']   `short` = 2–4 sentences
+     * @param {Array<{title?:string,url:string,description?:string,date?:string}>} [opts.results]
+     *        results from the host application's own search API (skips the built-in search)
+     * @param {boolean} [opts.search=true]            `false` = skip the built-in search, use DeepAI's
+     * @param {string[]} [opts.providers]             subset of WebSearch.PROVIDERS for this call
+     * @param {number}  [opts.maxResults]             results handed to the model (default config.webSearchResults)
      * @param {number}  [opts.minWords=150]           long form only: retry once below this (0 disables)
      * @param {boolean} [opts.includeSources=true]    append the *Sources:* block to `text`
      * @param {number}  [opts.maxSources=5]           sources listed in `text` (the array is not capped)
@@ -812,12 +888,12 @@ class AlexaAI {
      * @param {string}  [opts.model]
      * @param {string}  [opts.userName]
      * @param {AbortSignal} [opts.signal]
-     * @returns {Promise<{ok:boolean, text:string, answer:string, sources:Array<{title:string|null,url:string|null,description:string|null}>, words:number, attempts:number, model?:string|null, error?:string, message?:string}>}
+     * @returns {Promise<{ok:boolean, text:string, answer:string, sources:Array<{title:string|null,url:string|null,description:string|null,date?:string|null,provider?:string,cited?:boolean}>, grounded:boolean, providers:string[], words:number, attempts:number, via:'model'|'digest', model?:string|null, error?:string, message?:string}>}
      */
     async searchWeb(query, opts = {}) {
         const question = String(query ?? '').trim();
         const failure = (error, message, extra = {}) => ({
-            ok: false, text: '', answer: '', sources: [], words: 0, attempts: 0, error, message, ...extra,
+            ok: false, text: '', answer: '', sources: [], grounded: false, providers: [], words: 0, attempts: 0, via: 'model', error, message, ...extra,
         });
         if (!question) return failure('VALIDATION_ERROR', 'searchWeb(): query is required');
 
@@ -826,18 +902,48 @@ class AlexaAI {
         const maxSources = Number.isFinite(opts.maxSources) ? opts.maxSources : 5;
         const minWords = detail === 'long' && Number.isFinite(opts.minWords) ? Math.max(0, opts.minWords) : detail === 'long' ? 150 : 0;
 
-        const request = { search: true, webAccess: true, model: opts.model, signal: opts.signal };
+        // ---- 1. search ------------------------------------------------------
+        let results = WebSearch.normalise(opts.results, 'caller');
+        let providers = results.length ? ['caller'] : [];
+        if (!results.length && opts.search !== false) {
+            const found = await this.webSearch.search(question, {
+                providers: opts.providers,
+                maxResults: opts.maxResults,
+                signal: opts.signal,
+            });
+            results = found.results;
+            providers = found.providers;
+            if (!results.length && this.config.debug) {
+                this.log.debug?.(
+                    `[AlexaAI] searchWeb: no web results for "${question}" ` +
+                        (found.errors.length ? `(${found.errors.map((e) => `${e.provider}: ${e.message}`).join('; ')})` : '') +
+                        ' — falling back to DeepAI web access'
+                );
+            }
+        }
+        const grounded = results.length > 0;
+
+        // ---- 2. ask the model ---------------------------------------------
+        const request = { search: !grounded, webAccess: !grounded, model: opts.model, signal: opts.signal };
         const messages = this.prompts.build({
-            message: WebAnswer.prompt(question, { detail, language: opts.language, instructions: opts.instructions }),
+            message: WebAnswer.prompt(question, {
+                detail,
+                results: grounded ? results : null,
+                language: opts.language,
+                instructions: opts.instructions,
+            }),
             memories: {},
             history: [],
             userName: opts.userName || null,
         });
 
+        let reply;
+        let result;
+        let attempts = 0;
         try {
-            let reply = await this.client.chatDetailed(messages, request);
-            let result = this._webAnswerFrom(reply);
-            let attempts = 1;
+            reply = await this.client.chatDetailed(messages, request);
+            result = this._webAnswerFrom(reply, results);
+            attempts = 1;
 
             if (minWords && result.words < minWords && result.answer) {
                 // Second chance: keep the first reply in the transcript so the
@@ -845,12 +951,12 @@ class AlexaAI {
                 const retryMessages = [
                     ...messages,
                     { role: 'assistant', content: reply.text },
-                    { role: 'user', content: WebAnswer.expandPrompt(question, result.words) },
+                    { role: 'user', content: WebAnswer.expandPrompt(question, result.words, { grounded }) },
                 ];
                 attempts = 2;
                 try {
                     const second = await this.client.chatDetailed(retryMessages, request);
-                    const candidate = this._webAnswerFrom(second, result.sources);
+                    const candidate = this._webAnswerFrom(second, results, result.sources);
                     if (candidate.words > result.words) {
                         reply = second;
                         result = candidate;
@@ -859,34 +965,75 @@ class AlexaAI {
                     this.log.debug?.(`[AlexaAI] searchWeb expansion failed, keeping first reply: ${err.message}`);
                 }
             }
-
-            const { answer, sources, words } = result;
-            if (!answer && !sources.length) return failure('DEEPAI_EMPTY', 'DeepAI returned no answer', { attempts });
-
-            const text = WebAnswer.render(answer, sources, { includeSources: includeSources || !answer, maxSources });
-            return { ok: true, text, answer, sources, words, attempts, model: reply.model || null };
         } catch (err) {
             this.log.warn?.(`[AlexaAI] searchWeb failed: ${err.message}`);
-            return failure(err.code || 'SEARCH_FAILED', err.message);
+            if (!grounded) return failure(err.code || 'SEARCH_FAILED', err.message, { attempts });
+            // The search worked even though the model did not: show the results.
+            const sources = AlexaAI._groundedSources(results, []);
+            return {
+                ok: true,
+                text: WebAnswer.render(WebAnswer.digest(results), sources, { includeSources, maxSources }),
+                answer: WebAnswer.digest(results),
+                sources,
+                grounded,
+                providers,
+                words: 0,
+                attempts,
+                via: 'digest',
+                model: null,
+                error: err.code || 'SEARCH_FAILED',
+                message: err.message,
+            };
         }
+
+        // ---- 3. assemble ----------------------------------------------------
+        const { answer, sources, words } = result;
+        if (!answer && !sources.length) return failure('DEEPAI_EMPTY', 'DeepAI returned no answer', { attempts, grounded, providers });
+
+        const text = WebAnswer.render(answer, sources, { includeSources: includeSources || !answer, maxSources });
+        return { ok: true, text, answer, sources, grounded, providers, words, attempts, via: 'model', model: reply.model || null };
     }
 
     /**
      * @private Turn one chat reply into `{ answer, sources, words }`.
-     * Structured packet sources come first (they carry descriptions), then
-     * whatever the model listed itself; duplicates collapse by URL.
+     *
+     * Grounded (we searched): citation markers `[n]` are removed from the
+     * prose and decide the order of the sources; any URL the model wrote is
+     * discarded. Ungrounded: DeepAI's web-results packet comes first (it
+     * carries descriptions), then whatever the model listed; duplicates
+     * collapse by URL.
      */
-    _webAnswerFrom(reply, carried = []) {
+    _webAnswerFrom(reply, results = [], carried = []) {
         let formatted = ResponseFormatter.format(MemoryExtractor.strip(reply.text));
         // Keep third-party vendor names: this is research output, not the
         // assistant introducing herself. WebAnswer removes the sentences in
         // which the model talks about *itself*.
         formatted = this.identityGuard.sanitise(formatted, false, { vendors: false });
         const parsed = WebAnswer.parse(formatted);
+
+        if (results.length) {
+            const { text, cited } = WebAnswer.extractCitations(WebAnswer.stripUrls(parsed.text, results), results.length);
+            return { answer: text, sources: AlexaAI._groundedSources(results, cited), words: WebAnswer.wordCount(text) };
+        }
         const sources = WebAnswer.mergeSources(AlexaAI._sources(reply.webResults), parsed.sources, carried);
         return { answer: parsed.text, sources, words: WebAnswer.wordCount(parsed.text) };
     }
 
+    /** @private search results as sources: cited ones first, in citation order. */
+    static _groundedSources(results, cited) {
+        const order = [...cited.map((n) => n - 1), ...results.map((_, i) => i).filter((i) => !cited.includes(i + 1))];
+        return order
+            .filter((i) => results[i])
+            .map((i) => ({
+                title: results[i].title || null,
+                url: results[i].url,
+                description: results[i].description || null,
+                date: results[i].date || null,
+                provider: results[i].provider || null,
+                cited: cited.includes(i + 1),
+            }));
+    }
+
     /** Is DeepAI reachable and is the key still good? */
     async deepaiHealth() {
         const started = Date.now();
@@ -912,7 +1059,8 @@ class AlexaAI {
     /** @private the image url carried by an /api/* or tool response. */
     static _outputUrl(data) {
         if (!data || typeof data !== 'object') return null;
-        const url = data.output_url || data.share_url || data.url || (Array.isArray(data.output) ? data.output[0] : null);
+        // Prefer share_url (stable, public) over output_url.
+        const url = data.share_url || data.output_url || data.url || (Array.isArray(data.output) ? data.output[0] : null);
         return typeof url === 'string' && url ? url : null;
     }
 

package/src/core/Config.js

@@ -42,7 +42,12 @@ class Config {
         const opts = options || {};
 
         // ---- Accept several aliases so the host bot can stay terse ----------
-        const key = opts.key || opts.apiKey || opts.deepaiKey || process.env.DEEPAI_API_KEY;
+        const key =
+            opts.key ||
+            opts.apiKey ||
+            opts.deepaiKey ||
+            process.env.DEEPAI_KEY ||
+            process.env.DEEPAI_API_KEY;
         const postgresUrl =
             opts.postgresUrl ||
             opts.postgresURL ||
@@ -107,6 +112,22 @@ class Config {
         ]);
         this.imageModel = opts.imageModel || 'text2img';
 
+        // ---- Anonymous device identity ---------------------------------------
+        // Stable device identifier sent as the `deepai_device_id` cookie.
+        // Anonymous /api/* generation is rate-limited per device, so the id
+        // is kept stable per instance; pass your own to share an existing
+        // device quota.
+        this.deviceId = opts.deviceId || process.env.DEEPAI_DEVICE_ID || null;
+
+        // ---- Engine web search (searchWeb) ----------------------------------
+        // The engine searches first and hands real results to the model, so
+        // every URL the bot shows comes from a search, never from the model.
+        this.webSearch = opts.webSearch !== false;
+        this.webSearchProviders = Config._list(opts.webSearchProviders, ['bing', 'bing-news', 'wikipedia', 'google-news', 'duckduckgo']);
+        this.webSearchTimeout = Config._int(opts.webSearchTimeout, 8000, 500, 60000);
+        this.webSearchResults = Config._int(opts.webSearchResults, 8, 1, 30);
+        this.webSearchProvider = typeof opts.webSearchProvider === 'function' ? opts.webSearchProvider : null;
+
         // ---- Chat request feature flags (mirrors the deepai.org client) -----
         this.enabledTools = Config._list(opts.enabledTools, ['image_generator', 'image_editor']);
         this.toolActivitySupport = opts.toolActivitySupport !== false;
@@ -160,7 +181,7 @@ class Config {
         this.retryDelay = Config._int(opts.retryDelay, 800, 0, 30000);
         this.userAgent =
             opts.userAgent ||
-            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36';
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36';
 
         // ---- Database --------------------------------------------------------
         this.autoMigrate = opts.autoMigrate !== false; // default true

package/src/core/DeepAIClient.js

@@ -43,6 +43,10 @@ class DeepAIClient {
         this._keyIndex = 0;
         this.sessionUuid = DeepAIClient.uuid();
 
+        // Stable per-instance device id sent as the `deepai_device_id`
+        // cookie (see Config.deviceId).
+        this.deviceId = this.config.deviceId || DeepAIClient.randomDeviceId();
+
         if (typeof fetch !== 'function') {
             throw new DeepAIError(
                 'Global fetch() is unavailable. AlexaAI requires Node.js 18+ (or install undici).',
@@ -71,7 +75,7 @@ class DeepAIClient {
             return true;
         }
         if (this.config.autoKeyRotation) {
-            const fresh = DeepAIClient.generateTryItKey();
+            const fresh = DeepAIClient.generateTryItKey(this.config.userAgent);
             this._keys.push(fresh);
             this._keyIndex = this._keys.length - 1;
             if (this.config.debug) this.log.warn?.('[AlexaAI] Minted a fresh anonymous DeepAI key');
@@ -81,22 +85,98 @@ class DeepAIClient {
     }
 
     /**
-     * Anonymous "try it" key in the shape deepai.org generates in-browser:
-     * `tryit-<10 digits>-<32 hex>`.
+     * Anonymous "try it" key: `tryit-<digits>-<32 hex>`.
+     *
+     * The hex part is a deterministic hash over the User-Agent:
+     *      H(UA + H(UA + H(UA + digits + SALT)))
+     * and is validated server-side against the request's User-Agent header,
+     * so the key must be derived from the UA the request will carry.
+     *
+     * Anonymous keys are single-use (one key == one request); `headers()`
+     * mints a fresh key per request whenever the active key is anonymous.
+     *
+     * @param {string} [userAgent] the User-Agent the request will carry
+     * @returns {string}
      */
-    static generateTryItKey() {
-        const digits = Array.from({ length: 10 }, () => Math.floor(Math.random() * 10)).join('');
-        const hex = Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join('');
-        return `tryit-${digits}-${hex}`;
+    static generateTryItKey(userAgent) {
+        const ua = String(
+            userAgent ||
+                'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36'
+        );
+        const digits = String(Math.round(Math.random() * 100000000000));
+        const salt = 'hackers_become_a_little_stinkier_every_time_they_hack';
+        const H = DeepAIClient._islandHash;
+        const hash = H(ua + H(ua + H(ua + digits + salt)));
+        return `tryit-${digits}-${hash}`;
+    }
+
+    /** True for anonymous `tryit-…` keys (single-use, hash-validated). */
+    static isTryItKey(key) {
+        return /^tryit-\d+-[0-9a-f]{32}$/i.test(String(key || ''));
+    }
+
+    /**
+     * Random device id for the `deepai_device_id` cookie:
+     * 32 random bytes encoded as base64url.
+     */
+    static randomDeviceId() {
+        const bytes = typeof crypto !== 'undefined' && crypto.getRandomValues
+            ? crypto.getRandomValues(new Uint8Array(32))
+            : Buffer.from(Array.from({ length: 32 }, () => Math.floor(Math.random() * 256)));
+        return Buffer.from(bytes).toString('base64url');
+    }
+
+    /**
+     * Deterministic hash used to derive anonymous key material from the
+     * User-Agent (see `generateTryItKey`). The integer/bit-level behaviour
+     * is intentional — do not simplify it.
+     * @private
+     */
+    static _islandHash(input) {
+        const a = [];
+        for (let b = 0; 64 > b; ) a[b] = 0 | (4294967296 * Math.sin(++b % Math.PI));
+        let d, e, f, g = [(d = 1732584193), (e = 4023233417), ~d, ~e], h = [];
+        const l = unescape(encodeURI(input)) + '\u0080';
+        let k = l.length;
+        let c = (--k / 4 + 2) | 15;
+        for (h[--c] = 8 * k; ~k; ) h[k >> 2] |= l.charCodeAt(k) << (8 * k--);
+        for (let b = 0, m = 0; b < c; b += 16) {
+            for (k = g; 64 > m; k = [ (f = k[3]), d + (((f = k[0] + [d & e | ~d & f, f & d | ~f & e, d ^ e ^ f, e ^ (d | ~f)][(k = m >> 4)] + a[m] + ~~h[b | [m, 5 * m + 1, 3 * m + 5, 7 * m][k] & 15]) << (k = [7, 12, 17, 22, 5, 9, 14, 20, 4, 11, 16, 23, 6, 10, 15, 21][4 * k + (m++ % 4)])) | (f >>> -k)), d, e ]) {
+                d = k[1] | 0;
+                e = k[2];
+            }
+            for (m = 4; m; ) g[--m] += k[m];
+        }
+        let result = '';
+        for (let i = 0; 32 > i; ) result += ((g[i >> 3] >> 4 * (1 ^ i++)) & 15).toString(16);
+        return result.split('').reverse().join('');
     }
 
-    /** Browser-identical headers. DeepAI rejects requests without an origin. */
+
+    /** True when the active key is an anonymous single-use `tryit-…` key. */
+    get usingTryItKey() {
+        return DeepAIClient.isTryItKey(this.apiKey);
+    }
+
+    /**
+     * Browser-identical headers. DeepAI rejects requests without an origin.
+     *
+     * Anonymous `tryit-…` keys are single-use and validated against a hash
+     * of the User-Agent, so whenever the active key is anonymous a fresh
+     * key is minted here for this request.
+     */
     headers(extra = {}) {
+        let apiKey = this.apiKey;
+        if (DeepAIClient.isTryItKey(apiKey)) {
+            apiKey = DeepAIClient.generateTryItKey(this.config.userAgent);
+            this._keys[this._keyIndex] = apiKey;
+        }
         return {
-            'api-key': this.apiKey,
+            'api-key': apiKey,
             Origin: this.config.origin,
             Referer: `${this.config.origin}/`,
             'User-Agent': this.config.userAgent,
+            ...(this.deviceId ? { Cookie: `deepai_device_id=${this.deviceId}` } : {}),
             ...extra,
         };
     }
@@ -561,7 +641,7 @@ class DeepAIClient {
         if (data?.err) {
             throw DeepAIClient._toError(200, JSON.stringify(data), String(data.err));
         }
-        if (typeof data?.status === 'string' && !data.output_url && !data.output && !data.id) {
+        if (typeof data?.status === 'string' && !data.share_url && !data.output_url && !data.output && !data.id) {
             throw DeepAIClient._toError(200, JSON.stringify(data), data.status);
         }
         return data;
@@ -572,6 +652,25 @@ class DeepAIClient {
         return this.runApi(this.config.imageModel || STANDARD_APIS.text2img, { text, ...extra }, options);
     }
 
+    /**
+     * Run a classic `/api/<name>` call with a one-shot anonymous tryit key,
+     * regardless of the configured key. Used as the fallback path when a
+     * registered key is refused ("Pro members only"); a fresh key is minted
+     * for this single request.
+     */
+    async runApiWithTryItKey(name, fields = {}, options = {}) {
+        const previousKeys = this._keys;
+        const previousIndex = this._keyIndex;
+        this._keys = [DeepAIClient.generateTryItKey(this.config.userAgent)];
+        this._keyIndex = 0;
+        try {
+            return await this.runApi(name, fields, options);
+        } finally {
+            this._keys = previousKeys;
+            this._keyIndex = previousIndex;
+        }
+    }
+
     /** Prompt-driven image edit (`/api/image-editor`). */
     async editImage(image, text, extra = {}) {
         return this.runApi(STANDARD_APIS.imageEditor, { image, text, ...extra });
@@ -711,7 +810,9 @@ class DeepAIClient {
     }
 
     static _isRefusal(status) {
-        return /exceeded|paid|credits|api-key|api key|login|not allowed|forbidden|unauthori[sz]ed/i.test(status);
+        return /exceeded|paid|credits|api-key|api key|login|not allowed|forbidden|unauthori[sz]ed|pro members|good standing|model only available|please try this model/i.test(
+            status
+        );
     }
 
     /** @private magic-number sniff so uploads carry a real content type. */
@@ -749,6 +850,13 @@ class DeepAIClient {
             'api key',
             'api-key',
             'please login',
+            // refusal statuses returned by the API:
+            'pro members', // "APIs are only available for Pro members in good standing…"
+            'good standing',
+            'model only available', // "model only available to (logged in|paid) users"
+            'signed in try-it quota exceeded',
+            'insufficient_credits',
+            'pro user out of credits',
         ];
         if (quotaHints.some((h) => lowered.includes(h))) {
             return new QuotaExceededError(`DeepAI refused the request: ${msg}`, { status, body });