xtrawl 0.1.0 → 0.1.1

package/DOCUMENTATION.md

@@ -8,6 +8,7 @@ the command line. XTrawl is an authenticated, read-only collector for public X d
 - [Install](#install)
 - [Authenticate](#authenticate)
 - [Use multiple accounts](#use-multiple-accounts)
+- [Own account state](#own-account-state)
 - [Use a proxy](#use-a-proxy)
 - [Use the TypeScript API](#use-the-typescript-api)
 - [Search filters](#search-filters)
@@ -161,6 +162,64 @@ usable `auth_token` and `ct0` values. XTrawl does not perform interactive userna
 If you want to reuse accounts already stored in the configured SQLite database without provisioning
 new input, create the client with `provision: false`.
 
+## Own account state
+
+SQLite is the default account store. A TypeScript application can instead implement the exported
+`AccountStateStore` interface and keep account state in its own database, vault, or service:
+
+```ts
+import { XTrawl, type AccountStateStore } from "xtrawl";
+
+const accountStore: AccountStateStore = createMyAccountStore();
+
+const client = await XTrawl.create({
+  accountStore,
+  dbPath: "./state/runs-and-cursors.db",
+});
+```
+
+A custom store must be passed to `await XTrawl.create()`. The synchronous constructor rejects it
+because account provisioning and initialization may be asynchronous. `dbPath` remains active for
+run records, pagination checkpoints, and manifest caching; only account state moves to the adapter.
+
+The store owns these operations:
+
+| Method | Required behavior |
+| --- | --- |
+| `list`, `findByUsername`, `upsert`, `delete` | Persist records; `upsert` merges fields and cookie keys while preserving omitted fields |
+| `replaceAll` | Atomically replace all account records |
+| `acquireLease` | Atomically choose and lease one eligible account |
+| `renewLease` | Extend only the matching active lease |
+| `completeLease` | Atomically clear the lease, record usage, and apply health/cooldown state |
+
+Every method may return its result directly or in a promise. Lease operations must be atomic across
+all workers or processes sharing the store. The request passed to `acquireLease` includes the current
+time, generated lease ID, expiry, UTC date, authentication requirement, and configured daily limits.
+
+### Export and restore sessions
+
+Use `client.accounts` when the application needs to persist or transfer reusable session state:
+
+```ts
+const state = await client.accounts.exportState({ includeSecrets: true });
+await mySecretStore.set("xtrawl/accounts", state);
+
+const saved: unknown = await mySecretStore.get("xtrawl/accounts");
+await client.accounts.restoreState(saved, { mode: "merge" });
+```
+
+Snapshots are versioned and validated at restore time. They include cookies, authentication and
+CSRF tokens, optional bearer tokens and proxies, usage counters, cooldown state, and last-error
+metadata. They exclude storage IDs, active lease ownership, passwords, email credentials, and
+two-factor secrets. `merge` upserts by username. `replace` calls the store's atomic `replaceAll`.
+
+`includeSecrets: true` is intentionally required: exported state can authenticate as the supplied
+accounts. Keep snapshots in an encrypted caller-owned secret store and never print, log, or commit
+them.
+
+Other async account operations include `summary()`, `list()`, `get()`, `import()`, `setProxy()`,
+`repair()`, and `delete()`. Listings are redacted unless `revealSecrets` is explicitly requested.
+
 ## Use a proxy
 
 Set one proxy for all accounts:
@@ -652,7 +711,8 @@ XTrawl caches it in SQLite and can use a stale cached value when a refresh fails
 
 ## Understand storage and account health
 
-XTrawl uses SQLite for operational state:
+XTrawl uses SQLite for run, checkpoint, and manifest state. SQLite is also the default account-state
+adapter:
 
 - Provisioned accounts and their health status
 - Exclusive account leases and lease expiry
@@ -669,12 +729,23 @@ leased, is not cooling down, and remains within configured local limits. After t
 - A rate-limit, network, proxy, or transient failure applies the corresponding cooldown.
 - An authentication rejection marks the account unusable so it is not selected again.
 
-SQLite coordinates account leases so separate work does not intentionally use the same stored
-account at the same time.
+The selected account store coordinates leases so separate work does not intentionally use the same
+account at the same time. A custom implementation must provide the same atomic lease guarantees.
 
 ## Manage local state
 
-`client.db` provides scoped operational maintenance without exposing the storage implementation:
+`client.accounts` is the storage-independent async account facade:
+
+```ts
+console.log(await client.accounts.summary());
+console.log(await client.accounts.list({ eligibleOnly: true }));
+
+await client.accounts.setProxy("collector-one", "socks5://127.0.0.1:1080");
+await client.accounts.repair("collector-one", true);
+await client.accounts.delete("old-account");
+```
+
+`client.db` provides SQLite-specific account maintenance and the run/checkpoint APIs:
 
 ```ts
 console.log(client.db.accountsSummary());
@@ -703,6 +774,7 @@ Treat the following as sensitive:
 - `auth_token`, `ct0`, bearer overrides, and complete cookie jars
 - SQLite state files containing provisioned account records
 - Proxy URLs containing usernames or passwords
+- Account-state snapshots returned by `client.accounts.exportState()`
 - Collected output that may contain personal data
 
 Follow these rules:

package/LICENSE

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

@@ -4,11 +4,24 @@
   Scrape public X posts, profiles, followers, and following.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/xtrawl"><img alt="npm version" src="https://img.shields.io/npm/v/xtrawl"></a>
+  <a href="https://github.com/ensp1re/xtrawl/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/ensp1re/xtrawl/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+</p>
+
 XTrawl collects public data from X without an official API key. Search posts, read profiles and
 timelines, inspect individual posts, collect follower and following lists, and save results as CSV or
 JSON. It splits long searches, rotates authorized accounts when requests fail, and saves resumable
 progress in SQLite. Use it from TypeScript or the command line.
 
+XTrawl is published on npm as [`xtrawl`](https://www.npmjs.com/package/xtrawl).
+
+> [!WARNING]
+> XTrawl is provided for educational and research purposes only. Automated scraping may violate
+> X's rules and can cause any account used with XTrawl to be restricted, locked, or permanently
+> banned. Use only accounts you own or are authorized to use, and proceed at your own risk.
+
 ## What XTrawl collects
 
 - Search results with date, account, phrase, hashtag, language, location, media, and engagement filters
@@ -151,33 +164,128 @@ flowchart LR
     Parse --> Result["Typed records"]
     Result --> Output["stdout / CSV / JSON"]
 
-    State[("SQLite state")] <--> Client
-    State <--> Pool
-    State <--> Query
+    Accounts[("Account state store")] <--> Pool
+    SQLite[("SQLite runs and checkpoints")] <--> Client
+    SQLite <--> Query
+    Accounts -.->|SQLite by default| SQLite
 ```
 
-For each operation, XTrawl leases an eligible account from SQLite, verifies its proxy when configured,
+For each operation, XTrawl leases an eligible account from the configured account store, verifies its proxy when configured,
 creates an authenticated session, builds a read-only web request, and paginates until the requested
 limit or another stop condition is reached. Searches default to the previous 30 days and divide that
 interval into concurrent tasks. Failed requests use bounded backoff, account switching, and session
 repair. Responses enter the application as unknown data and are narrowed into typed records at the
 engine boundary.
 
-SQLite tracks account health, request usage, leases, run history, resumable cursors, and cached
-operation manifests. It does not store collected posts or profiles unless you explicitly enable file
+SQLite tracks run history, resumable cursors, cached operation manifests, and—by default—account
+health, request usage, and leases. Applications may replace only the account-state boundary with
+their own store. XTrawl does not store collected posts or profiles unless you explicitly enable file
 output.
 
-## Accounts and proxies
+## Use multiple accounts
+
+Create a local `accounts.json` file containing one object per account. Each live account needs an
+`auth_token` and `ct0` value from the same authorized browser session. You can provide them as named
+fields or inside `cookies`:
+
+```json
+[
+  {
+    "username": "collector-one",
+    "authToken": "replace-with-auth-token",
+    "csrfToken": "replace-with-ct0"
+  },
+  {
+    "username": "collector-two",
+    "cookies": {
+      "auth_token": "replace-with-auth-token",
+      "ct0": "replace-with-ct0"
+    },
+    "proxy": "socks5://proxy-user:proxy-password@127.0.0.1:1080"
+  }
+]
+```
+
+Keep this file outside version control. Load the complete pool with the CLI:
+
+```bash
+npx xtrawl \
+  --cookies-file ./accounts.json \
+  --db-path ./state/xtrawl.db \
+  --concurrency 5 \
+  search "typescript" \
+  --limit 100
+```
+
+Or load it from the TypeScript API:
+
+```ts
+const client = await XTrawl.create({
+  accountsFile: "./accounts.json",
+  dbPath: "./state/xtrawl.db",
+  concurrency: 5,
+});
+
+console.log(client.poolSummary);
+```
+
+XTrawl imports the accounts into SQLite and leases eligible accounts as work is scheduled. The
+default concurrency is five; loading more accounts does not make every account run at once. There is
+no configured account-count limit, but very large pools have not been load-tested. A failed page is
+retried up to three times and may switch accounts twice by default. Rate-limit, network, proxy, and
+transient failures place the affected account into cooldown. A rejected session marks the account
+unusable and attempts a CSRF-cookie repair before another account is selected.
+
+An account-level `proxy` takes precedence over the global `--proxy`. HTTP, HTTPS, and SOCKS5 proxies
+are supported. XTrawl does not currently accept a separate proxy list or automatically assign and
+reassign proxies; attach a proxy to each account when you need one-to-one account/proxy routing.
 
-For one account, pass `X_AUTH_TOKEN` and `X_CSRF_TOKEN` directly. For an account pool, provide a JSON,
-Netscape-cookie, or delimited account file with `--cookies-file`, or use the equivalent library
-options. A global proxy can be set with `--proxy`; library account records may also define their own
-HTTP, HTTPS, or SOCKS5 proxy.
+### Cookie lifecycle
 
-XTrawl selects only accounts that have usable authentication, are outside cooldown, are not already
-leased, and remain within configured daily limits. Rate-limit and transient failures trigger a
-cooldown and can switch the current task to another account. Authentication failures attempt a CSRF
-cookie repair before the account remains unusable.
+XTrawl does not refresh cookies after every request and does not persist `Set-Cookie` response
+updates. It reuses each stored cookie jar until the session fails. `XTrawl.create()` tries to obtain a
+missing `ct0` cookie when an `auth_token` is available, and an authentication failure triggers the
+same repair path. If the `auth_token` has expired or been revoked, replace the stored cookies before
+using that account again.
+
+XTrawl does not perform username/password, email, or two-factor login. Supplying those fields without
+valid session cookies does not make an account eligible for requests.
+
+## Own account state
+
+TypeScript applications can keep accounts in their own database or secret store by implementing
+`AccountStateStore`. The adapter owns account records, atomic lease acquisition and completion, and
+atomic replacement. Its methods may be synchronous or asynchronous; custom stores must be supplied
+through `XTrawl.create()`:
+
+```ts
+import { XTrawl, type AccountStateStore } from "xtrawl";
+
+const accountStore: AccountStateStore = createMyAccountStore();
+
+const client = await XTrawl.create({
+  accountStore,
+  dbPath: "./state/runs-and-cursors.db",
+});
+```
+
+`dbPath` still holds run history, checkpoints, and manifest cache. Account credentials, health,
+limits, cooldowns, and leases use the custom store.
+
+You can also move reusable session state between stores:
+
+```ts
+const state = await client.accounts.exportState({ includeSecrets: true });
+await mySecretStore.set("xtrawl/accounts", state);
+
+const saved = await mySecretStore.get("xtrawl/accounts");
+await client.accounts.restoreState(saved, { mode: "merge" });
+```
+
+Export requires the explicit `includeSecrets: true` acknowledgement because the snapshot contains
+authentication tokens, cookies, bearer overrides, and proxy credentials. It excludes account IDs,
+active leases, passwords, email credentials, and two-factor secrets. `merge` updates matching
+usernames; `replace` atomically replaces all accounts. Never log or commit a snapshot.
 
 ## Resume and save output
 
@@ -190,10 +298,11 @@ append records, and generated filenames include the query/date range or collecti
 
 ## Manage local state
 
-The library exposes safe account and run maintenance through `client.db`. It can list redacted
-accounts, import accounts, assign proxies, repair or disable an account, clear expired leases and
-checkpoints, reset local counters, inspect run history, and remove a named account. Destructive
-duplicate cleanup is a dry run unless explicitly enabled.
+Use the async `client.accounts` facade for redacted account listing, import, proxy assignment,
+repair, deletion, and explicit state export/restore. It works with SQLite and custom stores.
+
+`client.db` provides SQLite-specific account maintenance plus run and checkpoint inspection.
+Destructive duplicate cleanup is a dry run unless explicitly enabled.
 
 ## Safety and limitations
 
@@ -230,3 +339,17 @@ npm run verify
 The full gate checks formatting, linting, strict TypeScript compilation, unit tests, package and CLI
 smoke behavior, harness integrity, and context-budget limits. Live integration tests require
 caller-supplied credentials and are disabled unless explicitly enabled.
+
+## Contributing and security
+
+Bug reports, documentation fixes, and read-only collection improvements are welcome. Read
+[CONTRIBUTING.md](https://github.com/ensp1re/xtrawl/blob/main/CONTRIBUTING.md) before opening a pull
+request. Please do not propose posting, liking, following, messaging, or other account mutation
+features.
+
+Do not report vulnerabilities or credential leaks in a public issue. Follow the private disclosure
+process in [SECURITY.md](https://github.com/ensp1re/xtrawl/blob/main/SECURITY.md). By participating in
+the project, you agree to follow the
+[Code of Conduct](https://github.com/ensp1re/xtrawl/blob/main/CODE_OF_CONDUCT.md).
+
+XTrawl is available under the [MIT License](LICENSE).

package/dist/auth/account-state.d.ts

@@ -0,0 +1,3 @@
+import type { AccountStateSnapshot } from "../domain/account-state.js";
+export declare function parseAccountStateSnapshot(value: unknown): AccountStateSnapshot;
+//# sourceMappingURL=account-state.d.ts.map

package/dist/auth/account-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-state.d.ts","sourceRoot":"","sources":["../../src/auth/account-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAA8B,MAAM,4BAA4B,CAAC;AAInG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAqB9E"}

package/dist/auth/account-state.js

@@ -0,0 +1,85 @@
+import { normalizeProxyPayload } from "../config/validation.js";
+import { AccountStateError } from "../domain/errors.js";
+import { isRecord } from "../utils/guards.js";
+export function parseAccountStateSnapshot(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.accounts))
+        throw new AccountStateError("Account state must use schemaVersion 1 and contain accounts.");
+    if (typeof value.exportedAt !== "string" ||
+        !Number.isFinite(Date.parse(value.exportedAt)) ||
+        new Date(value.exportedAt).toISOString() !== value.exportedAt)
+        throw new AccountStateError("Account state exportedAt must be an ISO date string.");
+    const accounts = value.accounts.map((account, index) => parseSnapshotAccount(account, index));
+    const usernames = new Set();
+    for (const account of accounts) {
+        if (usernames.has(account.username))
+            throw new AccountStateError(`Account state contains duplicate username: ${account.username}.`);
+        usernames.add(account.username);
+    }
+    return {
+        schemaVersion: 1,
+        exportedAt: value.exportedAt,
+        accounts,
+    };
+}
+function parseSnapshotAccount(value, index) {
+    if (!isRecord(value) || typeof value.username !== "string" || !value.username.trim())
+        throw invalidAccount(index, "username must be a non-empty string");
+    if (!isRecord(value.cookies))
+        throw invalidAccount(index, "cookies must be an object");
+    const cookies = parseCookies(value.cookies, index);
+    const proxy = normalizeProxyPayload(value.proxy);
+    if (value.proxy !== undefined && proxy === undefined)
+        throw invalidAccount(index, "proxy must be a URL or host/port object");
+    const status = optionalStatus(value.status, index);
+    return {
+        username: value.username.trim(),
+        ...optionalString("authToken", value.authToken, index),
+        ...optionalString("csrfToken", value.csrfToken, index),
+        cookies,
+        ...optionalString("bearerToken", value.bearerToken, index),
+        ...(proxy === undefined ? {} : { proxy }),
+        ...(status === undefined ? {} : { status }),
+        ...optionalNonNegativeNumber("availableUntil", value.availableUntil, index),
+        ...optionalNonNegativeNumber("dailyRequests", value.dailyRequests, index),
+        ...optionalNonNegativeNumber("dailyTweets", value.dailyTweets, index),
+        ...optionalNonNegativeNumber("totalTweets", value.totalTweets, index),
+        ...optionalString("lastResetDate", value.lastResetDate, index),
+        ...optionalNonNegativeNumber("lastUsed", value.lastUsed, index),
+        ...optionalNonNegativeNumber("lastErrorCode", value.lastErrorCode, index),
+        ...optionalString("cooldownReason", value.cooldownReason, index),
+    };
+}
+function parseCookies(value, index) {
+    const cookies = {};
+    for (const [name, cookie] of Object.entries(value)) {
+        if (typeof cookie !== "string")
+            throw invalidAccount(index, "cookie values must be strings");
+        cookies[name] = cookie;
+    }
+    return cookies;
+}
+function optionalString(key, value, index) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "string")
+        throw invalidAccount(index, `${key} must be a string`);
+    return { [key]: value };
+}
+function optionalNonNegativeNumber(key, value, index) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        throw invalidAccount(index, `${key} must be a non-negative number`);
+    return { [key]: value };
+}
+function optionalStatus(value, index) {
+    if (value === undefined)
+        return undefined;
+    if (value !== 0 && value !== 1 && value !== 2)
+        throw invalidAccount(index, "status must be 0, 1, or 2");
+    return value;
+}
+function invalidAccount(index, reason) {
+    return new AccountStateError(`Invalid account state at accounts[${index}]: ${reason}.`);
+}
+//# sourceMappingURL=account-state.js.map

package/dist/auth/account-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-state.js","sourceRoot":"","sources":["../../src/auth/account-state.ts"],"names":[],"mappings":"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"}

package/dist/client/accounts.d.ts

@@ -0,0 +1,31 @@
+import type { ClientConfig } from "../config/types.js";
+import type { AccountStateExportOptions, AccountStateRestoreOptions, AccountStateSnapshot, AccountStateStore } from "../domain/account-state.js";
+import type { AccountRecord, AccountSummary, ProxySettings } from "../domain/accounts.js";
+import { type AccountImportOptions, type AccountListOptions } from "./database.js";
+export declare class XTrawlAccounts {
+    private readonly store;
+    private readonly config;
+    private readonly location;
+    private readonly onAccountsChanged?;
+    private cachedAccounts;
+    constructor(store: AccountStateStore, config: ClientConfig, location: string, onAccountsChanged?: ((accounts: readonly AccountRecord[]) => void) | undefined);
+    refresh(): Promise<void>;
+    initialize(accounts: readonly AccountRecord[]): void;
+    inspectCached(): readonly Record<string, unknown>[];
+    summary(): Promise<AccountSummary>;
+    list(options?: AccountListOptions): Promise<readonly Record<string, unknown>[]>;
+    get(username: string, options?: Pick<AccountListOptions, "includeCookies" | "revealSecrets">): Promise<Record<string, unknown> | undefined>;
+    import(options: AccountImportOptions): Promise<{
+        readonly processed: number;
+        readonly eligible: number;
+    }>;
+    delete(username: string): Promise<boolean>;
+    setProxy(username: string, proxy: string | ProxySettings): Promise<boolean>;
+    repair(username: string, forceRefresh?: boolean): Promise<boolean>;
+    exportState(options: AccountStateExportOptions): Promise<AccountStateSnapshot>;
+    restoreState(state: unknown, options?: AccountStateRestoreOptions): Promise<{
+        readonly restored: number;
+        readonly mode: "merge" | "replace";
+    }>;
+}
+//# sourceMappingURL=accounts.d.ts.map

package/dist/client/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../src/client/accounts.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,oBAAoB,EAEpB,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG1F,OAAO,EAAiB,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAElG,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IANrC,OAAO,CAAC,cAAc,CAAgC;gBAGnC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,CAAC,GAAE,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,KAAK,IAAI,aAAA;IAGtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,UAAU,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI;IAIpD,aAAa,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAI7C,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;IAKlC,IAAI,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IASnF,GAAG,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,GAAG,eAAe,CAAM,GACzE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAKlC,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;QAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IAOW,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBhE,WAAW,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAW9E,YAAY,CACvB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC;CAW9E"}

package/dist/client/accounts.js

@@ -0,0 +1,163 @@
+import { bootstrapCookiesFromAuthToken } from "../auth/bootstrap.js";
+import { parseAccountStateSnapshot } from "../auth/account-state.js";
+import { loadAccountsFileSync, loadInlineAccounts } from "../auth/loaders.js";
+import { accountInputToRecord } from "../auth/records.js";
+import { loadAccountFromEnvironmentSync } from "../config/environment.js";
+import { AccountStateError } from "../domain/errors.js";
+import { summarizeAccounts } from "../pool/account-pool.js";
+import { redactAccount } from "./database.js";
+export class XTrawlAccounts {
+    store;
+    config;
+    location;
+    onAccountsChanged;
+    cachedAccounts = [];
+    constructor(store, config, location, onAccountsChanged) {
+        this.store = store;
+        this.config = config;
+        this.location = location;
+        this.onAccountsChanged = onAccountsChanged;
+    }
+    async refresh() {
+        this.cachedAccounts = await this.store.list();
+        this.onAccountsChanged?.(this.cachedAccounts);
+    }
+    initialize(accounts) {
+        this.cachedAccounts = accounts;
+    }
+    inspectCached() {
+        return this.cachedAccounts.map((account) => redactAccount(account, {}));
+    }
+    async summary() {
+        await this.refresh();
+        return summarizeAccounts(this.cachedAccounts, this.config, this.location);
+    }
+    async list(options = {}) {
+        await this.refresh();
+        const now = Date.now();
+        return this.cachedAccounts
+            .filter((account) => !options.eligibleOnly || isEligible(account, this.config, now))
+            .filter((account) => !options.unusableOnly || account.status === 0)
+            .map((account) => redactAccount(account, options));
+    }
+    async get(username, options = {}) {
+        const account = await this.store.findByUsername(username);
+        return account ? redactAccount(account, options) : undefined;
+    }
+    async import(options) {
+        const accounts = loadImportAccounts(options);
+        for (const account of accounts)
+            await this.store.upsert({ ...account, proxy: account.proxy ?? options.proxy });
+        return { processed: accounts.length, eligible: (await this.summary()).eligible };
+    }
+    async delete(username) {
+        const deleted = await this.store.delete(username);
+        await this.refresh();
+        return deleted;
+    }
+    async setProxy(username, proxy) {
+        const account = await this.store.findByUsername(username);
+        if (!account)
+            return false;
+        await this.store.upsert({ ...account, proxy });
+        await this.refresh();
+        return true;
+    }
+    async repair(username, forceRefresh = false) {
+        const account = await this.store.findByUsername(username);
+        if (!account?.authToken)
+            return false;
+        if (!forceRefresh && account.csrfToken) {
+            await this.store.upsert({ ...account, status: 1, availableUntil: 0 });
+            await this.refresh();
+            return true;
+        }
+        const cookies = await bootstrapCookiesFromAuthToken(account.authToken, undefined, account.proxy);
+        if (!cookies?.ct0)
+            return false;
+        await this.store.upsert({
+            ...account,
+            status: 1,
+            availableUntil: 0,
+            csrfToken: cookies.ct0,
+            cookies: { ...account.cookies, ...cookies },
+        });
+        await this.refresh();
+        return true;
+    }
+    async exportState(options) {
+        if (!options || options.includeSecrets !== true)
+            throw new AccountStateError("exportState requires includeSecrets: true.");
+        const accounts = await this.store.list();
+        return {
+            schemaVersion: 1,
+            exportedAt: new Date().toISOString(),
+            accounts: accounts.map(toSnapshotRecord),
+        };
+    }
+    async restoreState(state, options = {}) {
+        const snapshot = parseAccountStateSnapshot(state);
+        const accounts = snapshot.accounts.map(fromSnapshotRecord);
+        const mode = options.mode ?? "merge";
+        if (mode !== "merge" && mode !== "replace")
+            throw new AccountStateError("restoreState mode must be merge or replace.");
+        if (mode === "replace")
+            await this.store.replaceAll(accounts);
+        else
+            for (const account of accounts)
+                await this.store.upsert(account);
+        await this.refresh();
+        return { restored: accounts.length, mode };
+    }
+}
+function loadImportAccounts(options) {
+    const accounts = [];
+    if (options.accounts)
+        accounts.push(...options.accounts.map(accountInputToRecord));
+    if (options.cookies !== undefined)
+        accounts.push(...loadInlineAccounts(options.cookies));
+    if (options.accountsFile)
+        accounts.push(...loadAccountsFileSync(options.accountsFile));
+    if (options.cookiesFile)
+        accounts.push(...loadAccountsFileSync(options.cookiesFile));
+    if (options.envFile)
+        accounts.push(...loadAccountFromEnvironmentSync(options.envFile).map(accountInputToRecord));
+    return accounts;
+}
+function toSnapshotRecord(account) {
+    return {
+        username: account.username,
+        ...(account.authToken ? { authToken: account.authToken } : {}),
+        ...(account.csrfToken ? { csrfToken: account.csrfToken } : {}),
+        cookies: account.cookies,
+        ...(account.bearerToken ? { bearerToken: account.bearerToken } : {}),
+        ...(account.proxy ? { proxy: account.proxy } : {}),
+        ...(account.status === 0 || account.status === 1 || account.status === 2
+            ? { status: account.status }
+            : {}),
+        ...copyOperationalState(account),
+    };
+}
+function fromSnapshotRecord(account) {
+    return { ...account, cookies: account.cookies };
+}
+function copyOperationalState(account) {
+    return {
+        ...(account.availableUntil === undefined ? {} : { availableUntil: account.availableUntil }),
+        ...(account.dailyRequests === undefined ? {} : { dailyRequests: account.dailyRequests }),
+        ...(account.dailyTweets === undefined ? {} : { dailyTweets: account.dailyTweets }),
+        ...(account.totalTweets === undefined ? {} : { totalTweets: account.totalTweets }),
+        ...(account.lastResetDate === undefined ? {} : { lastResetDate: account.lastResetDate }),
+        ...(account.lastUsed === undefined ? {} : { lastUsed: account.lastUsed }),
+        ...(account.lastErrorCode === undefined ? {} : { lastErrorCode: account.lastErrorCode }),
+        ...(account.cooldownReason === undefined ? {} : { cooldownReason: account.cooldownReason }),
+    };
+}
+function isEligible(account, config, now) {
+    return (account.status !== 0 &&
+        !(account.status === 2 && (account.availableUntil ?? 0) > now) &&
+        Boolean(account.authToken && account.csrfToken) &&
+        (account.dailyRequests ?? 0) < config.dailyRequestsLimit &&
+        (account.dailyTweets ?? 0) < config.dailyTweetsLimit);
+}
+//# sourceMappingURL=accounts.js.map