planvortex 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talia Softworks
+
+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,283 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/taliasoftworks/PlanVortexNode/main/assets/logo-horizontal-dark.png">
+  <img src="https://raw.githubusercontent.com/taliasoftworks/PlanVortexNode/main/assets/logo-horizontal.png" alt="PlanVortex" width="300">
+</picture>
+
+# planvortex
+
+Official Node.js client for the [PlanVortex](https://planvortex.com) API: connect social accounts,
+schedule and publish posts, read comments and messages, and verify webhooks.
+
+> **This is a server-side package. Do not use it in a browser.**
+> Authenticating uses the `client_credentials` flow, which needs your `client_secret`. A secret
+> inside a front-end bundle is your whole account handed over. To let _an end user_ connect their
+> own social account from a browser, issue a **temporal connect token** instead — it lasts an hour,
+> is tied to a single organization, and can only create accounts.
+
+```bash
+npm install planvortex
+```
+
+Requires **Node 20 or newer** (`fetch`, `FormData`, `Blob` and `fs.openAsBlob` are globals there)
+and has **zero runtime dependencies**.
+
+## Status
+
+**Early. Connecting accounts, the publishing path and the webhooks work; the inbox does not, yet.**
+
+| Phase | What it adds                                             | State   |
+| ----- | -------------------------------------------------------- | ------- |
+| 3     | Package skeleton: dual ESM/CJS build, tests, CI, release | done    |
+| 4     | Transport, authentication and errors                     | done    |
+| 5     | Types generated from the OpenAPI specification           | done    |
+| 6     | Resources: the publishing path                           | done    |
+| 7     | Resources: inbox and the rest                            | pending |
+| 8     | Webhooks                                                 | done    |
+| 9     | The account connection flow                              | done    |
+
+## Publishing
+
+```ts
+import { PlanVortex } from "planvortex";
+
+const pv = new PlanVortex({
+    clientId: process.env.PLANVORTEX_CLIENT_ID,
+    clientSecret: process.env.PLANVORTEX_CLIENT_SECRET,
+});
+
+// The accounts you can actually publish with. The server applies the same capability matrix it
+// publishes at GET /social_capabilities, so you never keep your own table of what each network does.
+const { data: accounts } = await pv.accounts.list(orgId, { capability: "publications" });
+
+// A path is the form that does not read the file into memory. A Buffer or a Blob also work.
+const upload = await pv.uploads.create(orgId, { file: "./hogaza.jpg" });
+
+const publication = await pv.publications.create(orgId, accounts[0]._id, {
+    social_network: accounts[0].social_network,
+    text: "Nuevo horno, nuevas hogazas",
+    files: [upload._id],
+    publish_date: new Date("2026-09-01T10:00:00Z"),
+});
+
+// A publication whose content does not fit the network is NOT an error: it is saved in state
+// `withErrors` with the reason inside. A try/catch alone reports it as published.
+if (publication.state === "withErrors") {
+    console.error(publication.publication_errors.map((failure) => failure.message));
+}
+```
+
+A complete, runnable version is in [examples/publish.ts](examples/publish.ts).
+
+Every listing pages the same way — `{data, total}` — and every one has an iterator that chains the
+pages for you:
+
+```ts
+const { data, total } = await pv.publications.list(orgId, { state: ["ready"], limit: 50 });
+
+for await (const publication of pv.publications.iterate(orgId, { state: ["ready"] })) {
+    // ...
+}
+```
+
+### What is available
+
+| Resource           | Methods                                                                                                                                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `pv.catalog`       | `socialNetworks`, `socialLimits`, `socialCapabilities`, `socialCommentActions`, `allowedAspectRatios`, `publicationLimits`, `allowedSocialPublications`, `allowedSocialMessages` — all cached in memory per client |
+| `pv.clients`       | `list`, `iterate`, `get`, `update`, `organizations`, `iterateOrganizations`, `createOrganization`, `updateOrganization`, `deleteOrganization`                                                                      |
+| `pv.organizations` | `get`, `update`, `remove`, `children`, `iterateChildren`, `createChild`, `limits`, `use`, `createConnectToken`                                                                                                     |
+| `pv.accounts`      | `list`, `iterate`, `get`, `update`, `remove`, `metrics`, `metricList`, `getPersistentMenu`, `setPersistentMenu`, `connectLinks`, `connect`, `enable`                                                               |
+| `pv.uploads`       | `create`, `list`, `iterate`, `get`, `update`, `remove`, `import`                                                                                                                                                   |
+| `pv.publications`  | `create`, `get`, `list`, `iterate`, `listByAccount`, `update`, `remove`, `retry`, `metrics`, `stats`, `listOnNetwork`                                                                                              |
+
+Anything not covered yet is reachable through the generic `pv.request(...)`, and the response types
+are already published, so you can annotate what comes back:
+
+```ts
+import type { Comment } from "planvortex";
+
+const { data } = await pv.request<{ comments: Comment[]; total: number }>({
+    method: "GET",
+    path: "/organizations/ORG_ID/comments",
+});
+```
+
+These types are generated from the same OpenAPI specification the
+[documentation](https://planvortex.com/documentation) is rendered from, so they cannot describe an
+endpoint that does not exist. One deliberate exception to "generated": every enumeration that grows
+with the product — `SocialNetwork`, `PublicationState`, `FileFormat` — is **open**. The known values
+autocomplete, and a network added to PlanVortex next month does not break your build.
+
+## Connecting a social account
+
+**An app cannot connect one.** Authorizing Instagram is an OAuth flow with a person in front of it,
+so app credentials are refused (error 519) by every endpoint of this flow. What an app does instead
+is mint a one-hour token, hand it to its user, and wait for them to come back. Your `client_secret`
+never leaves your server.
+
+```ts
+// On your server, when your user asks to connect a social account:
+const connect = await pv.organizations.createConnectToken(orgId, {
+    // Must be one of the app's registered redirect_urls, or you get error 532.
+    redirect_uri: "https://your-app.example/done",
+});
+
+response.redirect(connect.url); // PlanVortex takes over, and returns them to your redirect_uri
+```
+
+`connect.url` is the hosted path, and the one you want: PlanVortex asks which network, runs the
+OAuth, and shows the person which accounts to enable. `connect.token` is the same credential on its
+own, for when you would rather render the picker yourself:
+
+```ts
+const guest = pv.asTemporalToken(connect.token);
+const links = await guest.accounts.connectLinks(orgId); // one authorization URL per network
+```
+
+Three things that surprise everyone:
+
+- **A network that cannot be connected right now simply does not appear** in `connectLinks()`. That
+  is an answer, not a failure — Discord in an organization that has not saved its own bot
+  credentials, for instance.
+- **The network sends the user back to PlanVortex, not to you.** Its `redirect_uri` has to be
+  registered in the network's own app settings, so it can never be a URL of yours. Where _your_ user
+  ends up afterwards is the `redirect_uri` you passed to `createConnectToken`.
+- **A connected account is not an enabled account.** One authorization can produce several — a
+  Facebook user with four pages — and none of them takes a plan slot or publishes until
+  `accounts.enable()` is called on it. That is also the call that answers 706 when the plan is full.
+
+A complete, runnable version is in [examples/connect-flow.ts](examples/connect-flow.ts).
+
+## Webhooks
+
+PlanVortex `POST`s to your app's `webhook_url` when something happens. **The body is an array of
+changes**, and each one carries `field` telling you what it is.
+
+```ts
+import express from "express";
+import { planvortexWebhooks, isCommentChange, isMessageChange } from "planvortex/webhooks";
+
+const app = express();
+
+app.post(
+    "/webhooks/planvortex",
+    planvortexWebhooks({
+        secret: process.env.PLANVORTEX_CLIENT_SECRET!,
+        onChanges: async (changes) => {
+            for (const change of changes) {
+                if (isCommentChange(change)) await moderate(change.commentObj);
+                if (isMessageChange(change)) await reply(change.messageObj);
+            }
+        },
+    }),
+);
+```
+
+No `express.raw()` is needed in front: if nothing has parsed the body yet, the middleware reads the
+stream itself. It answers 200 when your handler returns, 401 when the signature does not match, 400
+when the body is not what it should be, and 500 when your handler throws.
+
+Outside Express — Hono, Fastify, a Next route handler — use the framework-agnostic function:
+
+```ts
+import { handleWebhookRequest } from "planvortex/webhooks";
+
+const changes = handleWebhookRequest({
+    body: await request.text(),          // the RAW body
+    headers: request.headers,            // a Headers or a plain object
+    secret: process.env.PLANVORTEX_CLIENT_SECRET!,
+});
+```
+
+Both throw `WebhookSignatureError` when the signature is missing or wrong, and `WebhookBodyError`
+when the body is not raw bytes, not JSON, or not an array. If you only want the check,
+`verifyWebhookSignature({payload, signature, secret})` returns a boolean and never throws on a
+malformed signature.
+
+### The events
+
+| `field` | What happened | Where the payload is |
+|---|---|---|
+| `new_account` | An account was connected | — |
+| `change_state_account` | An account changed state: broke, refreshed, disconnected | — |
+| `messages` | A message came in | `messageObj` |
+| `messaging_postbacks` | The contact pressed a button or a quick reply | `messageObj` |
+| `messaging_seen` | The contact read the conversation | `messageObj`, when we have it |
+| `messaging_error` | The network refused a message you sent | `messageObj.message_errors` |
+| `comments` | A comment came in | `commentObj` |
+| `integration_error` | An integration stopped working | `provider`, `error_code` |
+
+`isAccountStateChange`, `isMessageChange`, `isCommentChange` and `isIntegrationErrorChange` narrow
+a change to its own type. Use them rather than a `switch`: the union carries a member for the
+`field`s this version does not know yet — the list grows — and TypeScript cannot rule that one out
+of a `case`.
+
+Two things about the payload that are easy to get wrong. An **integration** change carries neither
+`id_account` nor `social_network`, because an integration hangs off the organization. And
+`messageObj` arrives **populated**: `contact_id`, `from_contact_id` and `message_options.files`
+carry whole objects rather than identifiers, which is what `messageContact`, `messageContactId`,
+`messageDirection` and `messageFiles` are for.
+
+**Meta repeats deliveries**, and PlanVortex does not retry a failed one. Deduplicate on
+`commentObj.external_id`, and if your work is slow, queue it and return.
+
+## Errors
+
+```ts
+import { PlanVortex, PlanLimitError, PlanVortexError } from "planvortex";
+
+try {
+    await pv.publications.create(orgId, accountId, { social_network: "instagram", text: "..." });
+} catch (error) {
+    if (error instanceof PlanLimitError) {
+        // Plan quota exhausted (codes 1300-1408). Retrying will not help.
+    } else if (error instanceof PlanVortexError) {
+        console.error(error.code, error.message, error.data, error.status);
+    }
+}
+```
+
+What the core does on your behalf: exchanges your credentials at `POST /oauth/token` and caches the
+token, refreshes it a minute before it expires, collapses concurrent calls into a **single** token
+request, retries 429/502/503/504 and network failures with exponential backoff and jitter, honours
+`Retry-After`, and turns every error body into a typed class. It never retries a domain error, and
+it never repeats a `POST` that reached the server.
+
+## Five things to know before you write any code
+
+**Classify errors by `code`, never by the HTTP status.** Every domain error travels with HTTP 400 —
+an expired token, a disconnected account, an exhausted plan quota and a text that is too long are
+all 400. Only error 520 (permissions) answers 401. An `if (res.status === 401) refresh()` is a silent
+bug: the token errors, 501 and 522, arrive inside a 400.
+
+**An app cannot connect social accounts.** Authorizing Instagram is an OAuth flow with a person in
+front of it, so those endpoints refuse app credentials. Your server issues a temporal connect token,
+your end user completes the flow with it, and the account lands in your organization.
+
+**A publication that does not fit the network is not an error.** It is stored with
+`state: "withErrors"` and the reason in `publication_errors` — which is an **array**. Check the
+state; a `try/catch` will not tell you.
+
+**`upload.public_path` expires.** It is a signed URL, not a permanent link: identical within the
+same hour, gone afterwards. Do not store it in your database — ask for the upload again.
+
+**A webhook signature is computed over the raw body.** Not over a re-serialized copy of the parsed
+JSON: the bytes differ and the signature never matches. Either let `planvortexWebhooks()` read the
+stream, or put `express.raw({ type: "application/json" })` in front of that one route. A global
+`express.json()` is what breaks it, and it breaks it silently.
+
+## Development
+
+```bash
+npm install
+npm run build        # dual ESM + CJS with both sets of types
+npm test             # no network, no credentials
+npm run typecheck
+npm run lint
+npm run generate     # regenerate the OpenAPI bundle and the types
+npm run check:exports  # publint + arethetypeswrong
+```
+
+## License
+
+MIT

package/dist/chunk-B4DEHU6Q.js

@@ -0,0 +1,140 @@
+// src/core/errors.ts
+var PLANVORTEX_ERROR_RANGES = [
+  { from: 500, to: 541, family: "auth" },
+  { from: 601, to: 612, family: "user" },
+  { from: 700, to: 715, family: "account" },
+  { from: 800, to: 810, family: "file" },
+  { from: 900, to: 960, family: "publication" },
+  { from: 1e3, to: 1003, family: "general" },
+  { from: 1100, to: 1111, family: "organization" },
+  { from: 1200, to: 1207, family: "role" },
+  { from: 1300, to: 1307, family: "plan_limit" },
+  { from: 1400, to: 1408, family: "plan_limit" },
+  { from: 1500, to: 1512, family: "messaging" },
+  { from: 1600, to: 1601, family: "contact" },
+  { from: 1900, to: 1906, family: "payment" },
+  { from: 2e3, to: 2099, family: "product" },
+  { from: 2100, to: 2199, family: "ai_plan" },
+  { from: 2200, to: 2299, family: "integration" }
+];
+var NO_ERROR_CODE = 0;
+var TOKEN_ERROR_CODES = [501, 522];
+var PlanVortexError = class extends Error {
+  /** El `code` del cuerpo, tal cual. {@link NO_ERROR_CODE} si el error no viene del catálogo. */
+  code;
+  /** La familia del rango: `auth`, `publication`, `plan_limit`... Ver {@link PLANVORTEX_ERROR_RANGES}. */
+  family;
+  /** El `data` del cuerpo. */
+  data;
+  /** Status HTTP, o `undefined` si nunca hubo respuesta. */
+  status;
+  /** `x-request-id`, si el despliegue lo pone. Hoy el servidor no lo emite; un proxy delante sí. */
+  requestId;
+  /** Segundos que pidió esperar la cabecera `Retry-After`, si llegó. */
+  retryAfter;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = new.target.name;
+    this.code = code;
+    this.family = options.family ?? errorFamilyForCode(code) ?? "unknown";
+    this.data = options.data ?? {};
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
+  }
+};
+var AuthError = class extends PlanVortexError {
+};
+var UserError = class extends PlanVortexError {
+};
+var AccountError = class extends PlanVortexError {
+};
+var FileError = class extends PlanVortexError {
+};
+var PublicationError = class extends PlanVortexError {
+};
+var OrganizationError = class extends PlanVortexError {
+};
+var PlanLimitError = class extends PlanVortexError {
+};
+var MessagingError = class extends PlanVortexError {
+};
+var ContactError = class extends PlanVortexError {
+};
+var ProductError = class extends PlanVortexError {
+};
+var AiPlanError = class extends PlanVortexError {
+};
+var IntegrationError = class extends PlanVortexError {
+};
+var PlanVortexConnectionError = class extends PlanVortexError {
+  /** `true` si lo que se agotó fue nuestro propio timeout, no la red. */
+  timeout;
+  constructor(message, options = {}) {
+    super(NO_ERROR_CODE, message, { ...options, family: "connection" });
+    this.timeout = options.timeout ?? false;
+  }
+};
+var PlanVortexAuthenticationError = class extends PlanVortexError {
+  /** `invalid_client`, `invalid_request`, `unsupported_grant_type`, `slow_down` o `server_error`. */
+  oauthError;
+  constructor(oauthError, description, options = {}) {
+    super(NO_ERROR_CODE, description, { ...options, family: "oauth" });
+    this.oauthError = oauthError;
+  }
+};
+var PlanVortexConfigError = class extends PlanVortexError {
+  constructor(message) {
+    super(NO_ERROR_CODE, message, { family: "config" });
+  }
+};
+function errorFamilyForCode(code) {
+  return PLANVORTEX_ERROR_RANGES.find((range) => code >= range.from && code <= range.to)?.family;
+}
+var FAMILY_CLASSES = {
+  auth: AuthError,
+  user: UserError,
+  account: AccountError,
+  file: FileError,
+  publication: PublicationError,
+  organization: OrganizationError,
+  plan_limit: PlanLimitError,
+  messaging: MessagingError,
+  contact: ContactError,
+  product: ProductError,
+  ai_plan: AiPlanError,
+  integration: IntegrationError
+};
+function isApiErrorBody(body) {
+  return typeof body === "object" && body !== null && typeof body.code === "number";
+}
+function createErrorFromResponse(input) {
+  const options = {
+    status: input.status,
+    ...input.requestId === void 0 ? {} : { requestId: input.requestId },
+    ...input.retryAfter === void 0 ? {} : { retryAfter: input.retryAfter }
+  };
+  if (isApiErrorBody(input.body)) {
+    const family = errorFamilyForCode(input.body.code);
+    const ErrorClass = (family === void 0 ? void 0 : FAMILY_CLASSES[family]) ?? PlanVortexError;
+    return new ErrorClass(input.body.code, input.body.message ?? "PlanVortex error", {
+      ...options,
+      data: input.body.data ?? {}
+    });
+  }
+  return new PlanVortexError(NO_ERROR_CODE, `HTTP ${input.status}`, {
+    ...options,
+    family: "http",
+    data: typeof input.body === "object" && input.body !== null ? input.body : { body: input.body }
+  });
+}
+function isPlanVortexError(error) {
+  return error instanceof PlanVortexError;
+}
+function isTokenError(error) {
+  return isPlanVortexError(error) && TOKEN_ERROR_CODES.includes(error.code);
+}
+
+export { AccountError, AiPlanError, AuthError, ContactError, FileError, IntegrationError, MessagingError, NO_ERROR_CODE, OrganizationError, PLANVORTEX_ERROR_RANGES, PlanLimitError, PlanVortexAuthenticationError, PlanVortexConfigError, PlanVortexConnectionError, PlanVortexError, ProductError, PublicationError, TOKEN_ERROR_CODES, UserError, createErrorFromResponse, errorFamilyForCode, isPlanVortexError, isTokenError };
+//# sourceMappingURL=chunk-B4DEHU6Q.js.map
+//# sourceMappingURL=chunk-B4DEHU6Q.js.map

package/dist/chunk-B4DEHU6Q.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/errors.ts"],"names":[],"mappings":"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","file":"chunk-B4DEHU6Q.js","sourcesContent":["/**\n * El catálogo de errores de PlanVortex, por rangos, y las clases que salen de él.\n *\n * LA REGLA, y no es negociable: **los errores se clasifican por `body.code`, nunca por el status\n * HTTP.** Todo error de dominio viaja con un 400 — un token caducado, una cuenta desconectada, el\n * cupo del plan agotado y un texto demasiado largo son los cuatro un 400. Sólo el 520 (permisos)\n * sale 401 y un fallo inesperado sale 500. Un `if (response.status === 401) refreshToken()` sería\n * un bug silencioso: los códigos de token, 501 y 522, viajan dentro de un 400.\n *\n * El catálogo del servidor crece cada mes, así que un código fuera de estos rangos NO es un error\n * del cliente: cae en la clase base con su `code` y su `message` intactos. Nunca se traga y nunca\n * se renombra.\n */\n\nexport type PlanVortexErrorRange = {\n    /** Primer código del rango, incluido */\n    from: number;\n    /** Último código del rango, incluido */\n    to: number;\n    /** Qué familia de problemas es */\n    family: string;\n};\n\nexport const PLANVORTEX_ERROR_RANGES: readonly PlanVortexErrorRange[] = [\n    { from: 500, to: 541, family: \"auth\" },\n    { from: 601, to: 612, family: \"user\" },\n    { from: 700, to: 715, family: \"account\" },\n    { from: 800, to: 810, family: \"file\" },\n    { from: 900, to: 960, family: \"publication\" },\n    { from: 1000, to: 1003, family: \"general\" },\n    { from: 1100, to: 1111, family: \"organization\" },\n    { from: 1200, to: 1207, family: \"role\" },\n    { from: 1300, to: 1307, family: \"plan_limit\" },\n    { from: 1400, to: 1408, family: \"plan_limit\" },\n    { from: 1500, to: 1512, family: \"messaging\" },\n    { from: 1600, to: 1601, family: \"contact\" },\n    { from: 1900, to: 1906, family: \"payment\" },\n    { from: 2000, to: 2099, family: \"product\" },\n    { from: 2100, to: 2199, family: \"ai_plan\" },\n    { from: 2200, to: 2299, family: \"integration\" },\n] as const;\n\n/**\n * El `code` que lleva un error que **no** trae código del servidor: un fallo de red, un timeout, un\n * 502 de un proxy con cuerpo HTML, o el propio constructor quejándose de la configuración.\n *\n * El servidor no emite nunca el 0, así que sirve de centinela sin pisar el catálogo. Cuál de esos\n * casos es se distingue por `family`: `connection`, `http`, `oauth`, `config` o `webhook`.\n */\nexport const NO_ERROR_CODE = 0;\n\n/**\n * Los dos códigos que significan \"tu token ya no sirve\". Los dos llegan **dentro de un 400**, que es\n * justo por lo que existe esta constante: quien mire el status no los va a encontrar.\n *\n * El 520 (permisos) NO está aquí a propósito: sale 401, pero pedir un token nuevo no lo arregla — a\n * la app le faltan permisos, y con un token recién emitido le seguirán faltando.\n */\nexport const TOKEN_ERROR_CODES: readonly number[] = [501, 522];\n\n/** Opciones de construcción de un error. Todas opcionales: un error siempre se puede construir. */\nexport interface PlanVortexErrorOptions {\n    /** El `data` del cuerpo — lo que el servidor adjuntó con `.withData({...})`. `{}` si no vino nada. */\n    data?: Record<string, unknown>;\n    /** Status HTTP. `undefined` cuando la petición no llegó a tener respuesta. */\n    status?: number;\n    /** `x-request-id` de la respuesta, si el despliegue lo pone delante. */\n    requestId?: string;\n    /** Segundos de la cabecera `Retry-After`, cuando la hay. */\n    retryAfter?: number;\n    /** El error original (un `TypeError` de `fetch`, por ejemplo). */\n    cause?: unknown;\n    /**\n     * Familia, sólo para los errores que NO salen del catálogo: `connection`, `http`, `oauth`,\n     * `config` y `webhook`. Los de dominio la deducen de su `code` y no la pasan nunca.\n     */\n    family?: string;\n}\n\n/**\n * La base de todo lo que lanza esta librería.\n *\n * Un `catch (e) { if (e instanceof PlanVortexError) }` los coge todos: los de dominio, los de red y\n * los de configuración. Para afinar están las subclases y el `code`.\n */\nexport class PlanVortexError extends Error {\n    /** El `code` del cuerpo, tal cual. {@link NO_ERROR_CODE} si el error no viene del catálogo. */\n    readonly code: number;\n    /** La familia del rango: `auth`, `publication`, `plan_limit`... Ver {@link PLANVORTEX_ERROR_RANGES}. */\n    readonly family: string;\n    /** El `data` del cuerpo. */\n    readonly data: Record<string, unknown>;\n    /** Status HTTP, o `undefined` si nunca hubo respuesta. */\n    readonly status: number | undefined;\n    /** `x-request-id`, si el despliegue lo pone. Hoy el servidor no lo emite; un proxy delante sí. */\n    readonly requestId: string | undefined;\n    /** Segundos que pidió esperar la cabecera `Retry-After`, si llegó. */\n    readonly retryAfter: number | undefined;\n\n    constructor(code: number, message: string, options: PlanVortexErrorOptions = {}) {\n        super(message, options.cause === undefined ? undefined : { cause: options.cause });\n        this.name = new.target.name;\n        this.code = code;\n        this.family = options.family ?? errorFamilyForCode(code) ?? \"unknown\";\n        this.data = options.data ?? {};\n        this.status = options.status;\n        this.requestId = options.requestId;\n        this.retryAfter = options.retryAfter;\n    }\n}\n\n/** 500-541 — tokens, apps de cliente, permisos. Incluye el 501 y el 522, los de token caducado. */\nexport class AuthError extends PlanVortexError {}\n/** 601-612 — el usuario final. */\nexport class UserError extends PlanVortexError {}\n/** 700-715 — cuentas sociales: desconectada, sin permisos en la red, sin refrescar. */\nexport class AccountError extends PlanVortexError {}\n/** 800-810 — ficheros: formato no admitido, demasiado grande, conversión fallida. */\nexport class FileError extends PlanVortexError {}\n/** 900-960 — publicaciones, incluidos los límites por red (caracteres, imágenes, duración). */\nexport class PublicationError extends PlanVortexError {}\n/** 1100-1111 — organizaciones, y el token temporal atado a una sola de ellas (1101). */\nexport class OrganizationError extends PlanVortexError {}\n/**\n * 1300-1307 y 1400-1408 — el cupo del plan, del cliente o de la organización.\n *\n * Es el error que un integrador **sí** quiere distinguir: no se arregla reintentando, se arregla\n * cambiando de plan. Por eso los dos rangos comparten clase.\n */\nexport class PlanLimitError extends PlanVortexError {}\n/** 1500-1512 — conversaciones, mensajes y plantillas. Exige plan de pago. */\nexport class MessagingError extends PlanVortexError {}\n/** 1600-1601 — contactos. */\nexport class ContactError extends PlanVortexError {}\n/** 2000-2099 — catálogos y productos (sólo Facebook e Instagram). */\nexport class ProductError extends PlanVortexError {}\n/** 2100-2199 — planes de publicaciones generados con IA. */\nexport class AiPlanError extends PlanVortexError {}\n/** 2200-2299 — integraciones: Google Drive, RSS. */\nexport class IntegrationError extends PlanVortexError {}\n\n/**\n * La petición no llegó a tener respuesta: DNS, conexión rechazada, socket cortado o timeout.\n *\n * No lleva código del catálogo porque el servidor nunca llegó a opinar.\n */\nexport class PlanVortexConnectionError extends PlanVortexError {\n    /** `true` si lo que se agotó fue nuestro propio timeout, no la red. */\n    readonly timeout: boolean;\n\n    constructor(message: string, options: PlanVortexErrorOptions & { timeout?: boolean } = {}) {\n        super(NO_ERROR_CODE, message, { ...options, family: \"connection\" });\n        this.timeout = options.timeout ?? false;\n    }\n}\n\n/**\n * `POST /oauth/token` rechazó las credenciales.\n *\n * Es el ÚNICO sitio del API con forma de error distinta: `{error, error_description}` de OAuth2, no\n * el `{code, message, data}` de todo lo demás. Y por eso el `code` es {@link NO_ERROR_CODE}: el\n * servidor tiene códigos para esto (538-541) pero **no los manda en el cuerpo**, así que ponerlos\n * aquí sería inventarse algo que nadie dijo. Lo que sí viaja es `oauthError`.\n */\nexport class PlanVortexAuthenticationError extends PlanVortexError {\n    /** `invalid_client`, `invalid_request`, `unsupported_grant_type`, `slow_down` o `server_error`. */\n    readonly oauthError: string;\n\n    constructor(oauthError: string, description: string, options: PlanVortexErrorOptions = {}) {\n        super(NO_ERROR_CODE, description, { ...options, family: \"oauth\" });\n        this.oauthError = oauthError;\n    }\n}\n\n/**\n * La librería está mal configurada y no ha llegado a salir de casa: sin credenciales, o instanciada\n * en un navegador (§ trampa 9 del roadmap).\n */\nexport class PlanVortexConfigError extends PlanVortexError {\n    constructor(message: string) {\n        super(NO_ERROR_CODE, message, { family: \"config\" });\n    }\n}\n\n/** La familia a la que pertenece un código, o `undefined` si cae fuera del catálogo conocido. */\nexport function errorFamilyForCode(code: number): string | undefined {\n    return PLANVORTEX_ERROR_RANGES.find((range) => code >= range.from && code <= range.to)?.family;\n}\n\n/**\n * Familia -> clase. Las que faltan —`general`, `role`, `payment` y cualquier rango nuevo— caen a\n * propósito en la clase base: existen en el servidor pero no son superficie de integración, y darles\n * clase propia sería prometer un `instanceof` que luego habría que mantener.\n */\nconst FAMILY_CLASSES: Record<string, typeof PlanVortexError> = {\n    auth: AuthError,\n    user: UserError,\n    account: AccountError,\n    file: FileError,\n    publication: PublicationError,\n    organization: OrganizationError,\n    plan_limit: PlanLimitError,\n    messaging: MessagingError,\n    contact: ContactError,\n    product: ProductError,\n    ai_plan: AiPlanError,\n    integration: IntegrationError,\n};\n\n/** El cuerpo de error del API: `{code, message, data}`. */\nexport interface ApiErrorBody {\n    code: number;\n    message?: string;\n    data?: Record<string, unknown>;\n}\n\nfunction isApiErrorBody(body: unknown): body is ApiErrorBody {\n    return typeof body === \"object\" && body !== null && typeof (body as ApiErrorBody).code === \"number\";\n}\n\n/**\n * Convierte una respuesta de error en la clase que le toca.\n *\n * Un cuerpo sin `code` —un 502 de un proxy, la página HTML de un balanceador— no es un error de\n * dominio: sale como clase base con `family: \"http\"` y el cuerpo entero en `data`, que es además lo\n * que necesita `auth.ts` para reconocer el `{error, error_description}` de OAuth2.\n */\nexport function createErrorFromResponse(input: {\n    body: unknown;\n    status: number;\n    requestId?: string | undefined;\n    retryAfter?: number | undefined;\n}): PlanVortexError {\n    const options: PlanVortexErrorOptions = {\n        status: input.status,\n        ...(input.requestId === undefined ? {} : { requestId: input.requestId }),\n        ...(input.retryAfter === undefined ? {} : { retryAfter: input.retryAfter }),\n    };\n\n    if (isApiErrorBody(input.body)) {\n        const family = errorFamilyForCode(input.body.code);\n        const ErrorClass = (family === undefined ? undefined : FAMILY_CLASSES[family]) ?? PlanVortexError;\n        return new ErrorClass(input.body.code, input.body.message ?? \"PlanVortex error\", {\n            ...options,\n            data: input.body.data ?? {},\n        });\n    }\n\n    return new PlanVortexError(NO_ERROR_CODE, `HTTP ${input.status}`, {\n        ...options,\n        family: \"http\",\n        data:\n            typeof input.body === \"object\" && input.body !== null\n                ? (input.body as Record<string, unknown>)\n                : { body: input.body },\n    });\n}\n\n/** ¿Es un error de esta librería? Útil en un `catch` donde no apetece importar la clase. */\nexport function isPlanVortexError(error: unknown): error is PlanVortexError {\n    return error instanceof PlanVortexError;\n}\n\n/**\n * ¿Dice este error que el token ya no sirve? (los códigos 501 y 522, los dos dentro de un 400).\n *\n * Es lo que dispara el único reintento con token nuevo del cliente.\n */\nexport function isTokenError(error: unknown): boolean {\n    return isPlanVortexError(error) && TOKEN_ERROR_CODES.includes(error.code);\n}\n"]}