tldrapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UnityCubed / TLDRapi
+
+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

@@ -0,0 +1,147 @@
+# tldrapi — Node.js / TypeScript SDK for TLDRapi
+
+Official Node.js + TypeScript client for the [TLDRapi summarization API](https://tldrapi.com). Summarize text at five quality tiers, 20+ built-in voice styles, custom voices for paid tiers. Typed results, typed errors, retries, zero third-party HTTP dependencies (uses the Node 18+ built-in `fetch`).
+
+**TLDRapi is distributed through the RapidAPI marketplace at launch.** Subscribe to the TLDRapi listing on RapidAPI to get your `X-RapidAPI-Key`, then pass it to the client as `rapidapiKey`.
+
+## Install
+
+```bash
+npm install tldrapi
+# or
+pnpm add tldrapi
+# or
+yarn add tldrapi
+```
+
+Node.js 18+.
+
+## Get your app's RapidAPI key
+
+1. Sign in at [rapidapi.com](https://rapidapi.com)
+2. Subscribe to the [TLDRapi Summarizer](https://rapidapi.com/thunderAPIs256/api/tldrapi-summarizer) listing (start with **BASIC** — free)
+3. Go to **Console** (top nav) → **Applications** → **Add App** (or open an existing one)
+4. In the App → **Authorizations** tab → click the copy icon next to your Authorization Key
+
+That's the app's `X-RapidAPI-Key`. Pass it to the SDK constructor.
+
+*Legacy path (deprecated): upper-right (?) → Legacy Developer Dashboard → Add New App → Authorization tab. The new Console path above is simpler.*
+
+The Authorization Key field is the same value in both places — RapidAPI just labels it differently depending on which interface you use:
+
+**New Console:**
+
+![RapidAPI Console — Authorization Method labeled "RAPIDAPI"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-console.png)
+
+**Legacy Developer Dashboard:**
+
+![RapidAPI Legacy Developer Dashboard — Authorization Method labeled "API key"](https://raw.githubusercontent.com/unitycubed/tldrapi-docs/main/img/rapidapi-key-label-legacy.png)
+
+
+
+## Quickstart
+
+```typescript
+import { TLDRapi } from 'tldrapi';
+
+const client = new TLDRapi({ rapidapiKey: 'YOUR_RAPIDAPI_KEY' });
+
+const result = await client.summarize(
+    'Some long text here...',
+    { tier: 'standard' },     // 'quick' | 'standard' | 'deep' | 'premium' | 'ultra'
+);
+
+console.log(result.summary);
+console.log(`used ${result.usage.outputTokens} output tokens on ${result.usage.modelUsed}`);
+console.log(`request id (for support): ${result.requestId}`);
+```
+
+Or plain JavaScript:
+
+```javascript
+const { TLDRapi } = require('tldrapi');
+const client = new TLDRapi({ rapidapiKey: 'YOUR_RAPIDAPI_KEY' });
+const result = await client.summarize('Long text...');
+```
+
+## Handling errors
+
+Every failure extends `TLDRapiError`. Catch the base for a safety net, or catch specific subclasses to branch on failure mode.
+
+```typescript
+import {
+    TLDRapi, TLDRapiError,
+    InsufficientCreditsError, RateLimitError,
+    LanguageNotSupportedError,
+} from 'tldrapi';
+
+try {
+    const result = await client.summarize(text, { tier: 'deep' });
+} catch (e) {
+    if (e instanceof InsufficientCreditsError) {
+        const topupUrl = (e.responseBody.options as any)?.top_up?.url;
+        // show user the topup options
+    } else if (e instanceof RateLimitError) {
+        await new Promise(r => setTimeout(r, (e.retryAfterSeconds || 60) * 1000));
+        // retry
+    } else if (e instanceof LanguageNotSupportedError) {
+        // English only at launch
+    } else if (e instanceof TLDRapiError) {
+        console.error(`TLDRapi error ${e.statusCode} (req ${e.requestId}): ${e.message}`);
+    } else {
+        throw e;
+    }
+}
+```
+
+## Quality tiers
+
+| Tier      | Credits/call | Max input tokens | Best for                          |
+|-----------|-------------:|-----------------:|-----------------------------------|
+| `quick`   |            1 |            4,000 | Short texts, low-latency previews |
+| `standard`|            5 |           16,000 | Default — modest documents        |
+| `deep`    |           30 |           32,000 | Longer content, deeper reasoning  |
+| `premium` |          110 |           64,000 | Substantial documents, high fidelity |
+| `ultra`   |          400 |          100,000 | Long-form / research-grade        |
+
+Credit costs are dynamic — check current with `client.rates()`.
+
+## Session pinning
+
+To keep the same model / session state across calls:
+
+```typescript
+const r1 = await client.summarize('First document');
+const r2 = await client.summarize('Second document', { sessionId: r1.sessionId });
+```
+
+## Overage
+
+Pay 2× rate instead of getting a 402 when your balance runs low:
+
+```typescript
+const result = await client.summarize(text, { allowOverage: true });
+```
+
+## Configuration
+
+| Option        | Default                            | Notes                                       |
+|---------------|------------------------------------|---------------------------------------------|
+| `rapidapiKey` | (required)                         | Your `X-RapidAPI-Key` from RapidAPI dashboard |
+| `rapidapiHost`| `tldrapi-summarizer.p.rapidapi.com`            | Override for staging listings only          |
+| `baseUrl`     | `https://tldrapi-summarizer.p.rapidapi.com`    | Change to point at a staging / mirror       |
+| `timeoutMs`   | 60_000                             | Per-request; deep tier can take 30s         |
+| `retries`     | 3                                  | Retries on 5xx + network errors only        |
+| `fetchImpl`   | `globalThis.fetch`                 | Pass `node-fetch` or `undici` for Node <18  |
+
+## Support
+
+- Issues: <https://github.com/unitycubedapps/tldrapi-node/issues>
+- Docs:   <https://unitycubed.dev/tldrapi/docs>
+- Legal:  <https://unitycubed.dev/tldrapi/legal>
+
+## License
+
+Released under the MIT License — see [LICENSE](LICENSE).
+
+Copyright (c) 2026 Ehren Biglari / Unity Cubed.

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TLDRapi HTTP client for Node 18+.
+ *
+ * Design:
+ *  - Uses the platform's built-in `fetch` (Node 18+). No third-party
+ *    HTTP dependency in the shipped package.
+ *  - Retries 5xx and network errors with exponential backoff + jitter,
+ *    default 3 attempts. 4xx and 429 are NEVER retried (429 auto-retry
+ *    would burn credits + worsen the throttle; caller should respect
+ *    the Retry-After exposed on RateLimitError).
+ *  - Per-request timeout via AbortController.
+ *  - Typed exceptions map 1:1 to server response shapes; see errors.ts.
+ */
+import { ConvertFileOptions, ConvertPdfOptions, ConvertResult, ConvertTextOptions, CustomPromptDetail, CustomPromptList, CustomPromptListOptions, CustomPromptResult, CustomPromptSubmitOptions, FileInput, PdfConvertResult, Rates, RatesHistory, SummarizeOptions, SummarizeResult, TLDRapiClientOptions, UsageRange, UsageStats } from './types';
+export declare const DEFAULT_RAPIDAPI_HOST = "tldrapi-summarizer.p.rapidapi.com";
+export declare class TLDRapi {
+    private readonly rapidapiKey;
+    private readonly rapidapiHost;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly fetchImpl;
+    constructor(opts: TLDRapiClientOptions);
+    summarize(inputText: string, options?: SummarizeOptions): Promise<SummarizeResult>;
+    rates(): Promise<Rates>;
+    usage(): Promise<UsageStats>;
+    convertJsonToText(text: string, opts?: ConvertTextOptions): Promise<ConvertResult>;
+    convertHtmlToText(text: string, opts?: ConvertTextOptions): Promise<ConvertResult>;
+    convertMdToText(text: string, opts?: ConvertTextOptions): Promise<ConvertResult>;
+    private convertText;
+    convertDocToText(file: FileInput, opts?: ConvertFileOptions): Promise<ConvertResult>;
+    convertDocToLatex(file: FileInput, opts?: ConvertFileOptions): Promise<ConvertResult>;
+    /** Deprecated alias for `convertDocToText`. Kept for backward compat. */
+    convertDocxToText(file: FileInput, opts?: ConvertFileOptions): Promise<ConvertResult>;
+    private convertFile;
+    convertPdfToLatex(file: FileInput, opts?: ConvertPdfOptions): Promise<PdfConvertResult>;
+    pdfStatus(jobId: string): Promise<PdfConvertResult>;
+    ratesHistory(): Promise<RatesHistory>;
+    usageRange(from: string, to: string): Promise<UsageRange>;
+    customPromptSubmit(voiceName: string, instruction: string, opts?: CustomPromptSubmitOptions): Promise<CustomPromptResult>;
+    customPromptsList(opts?: CustomPromptListOptions): Promise<CustomPromptList>;
+    customPromptGet(promptId: string): Promise<CustomPromptDetail>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,OAAO,EACH,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAElB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,yBAAyB,EAEzB,SAAS,EACT,gBAAgB,EAEhB,KAAK,EACL,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EAGpB,UAAU,EAEV,UAAU,EAEb,MAAM,SAAS,CAAC;AASjB,eAAO,MAAM,qBAAqB,sCAAsC,CAAC;AAoGzE,qBAAa,OAAO;IAChB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,oBAAoB;IAmBhC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAwCtF,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IA2BvB,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAiC5B,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;IAItF,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;IAItF,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;YAI5E,WAAW;IAmBnB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxF,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;IAI/F,yEAAyE;IACnE,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;YAIjF,WAAW;IAuBnB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuB3F,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAcnD,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC;IAQrC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAYzD,kBAAkB,CACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,yBAA8B,GACrC,OAAO,CAAC,kBAAkB,CAAC;IAexB,iBAAiB,CAAC,IAAI,GAAE,uBAA4B,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAahF,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;YAStD,OAAO;CA4CxB"}