@pimia/sdk 0.20.0 → 0.27.0

package/dist/central-api.js

@@ -0,0 +1,9 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ *
+ * Generado con `npm run generate:types` (scripts/generate-types.mjs), que
+ * añade UN transform al generador: `format: binary` sale como `Blob` y no
+ * como `string`. El porqué, en ese fichero.
+ */
+export {};

package/dist/central.d.ts

@@ -0,0 +1,607 @@
+/**
+ * Cliente del PLANO CENTRAL de Pimia para el integrador (cuenta de
+ * desarrollador): su cartera de clientes, los vínculos con cada instancia, sus
+ * clients OAuth, las invitaciones, el patrocinio y el traspaso de propiedad.
+ *
+ * No es el cliente de un tenant ({@link PimiaClient}, que habla con
+ * `https://{tenant}.pimia.es/api/v1` con un token OAuth por instancia): este
+ * habla con el ÁPICE (`https://pimia.es/api`) con el **token personal de
+ * Sanctum** de la cuenta de desarrollador, acotado por plano
+ * (galeote/factSaas#731): `desarrollador` abre `/desarrollador/*` y `central`
+ * abre invitaciones, patrocinio y traspaso. Cada operación del contrato dice
+ * cuál exige (`x-pimia-required-ability`); un token sin ella recibe un
+ * {@link MissingAbilityError} con la habilidad que falta.
+ *
+ * Lo que NO hace, a propósito: refrescar nada (el token personal no caduca ni
+ * rota; se revoca desde el panel) ni leer contenido fiscal de ningún cliente —
+ * a los datos de una instancia se llega por OAuth consentido, con el otro
+ * cliente.
+ *
+ * Los tipos salen de `spec/pimia-central-v1.json` (`./central-api`).
+ */
+import type { operations } from './central-api.js';
+/** El cuerpo JSON que pide una operación del contrato. */
+type Body<O extends keyof operations> = operations[O] extends {
+    requestBody: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : operations[O] extends {
+    requestBody?: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : never;
+/**
+ * Cuerpo de `POST /billing/sponsorship`: la instancia y el plan de canal con
+ * que se paga; `return_url` (1.4.0) es a dónde vuelve el integrador desde el
+ * Checkout del canal —solo se acepta el origen del panel central o el del
+ * ápice; lo demás vuelve al panel Vue—.
+ */
+export type SponsorshipRequest = Body<'billing.sponsor'>;
+/** Cuerpo de `POST /billing/portal` (1.4.0): `return_url`, con la misma regla que el patrocinio. */
+export type BillingPortalRequest = Body<'billing.portal'>;
+/** Cuerpo de `POST /tenant-invitations`: a quién se invita y quién paga (`billing`). */
+export type TenantInvitationRequest = Body<'tenantInvitation.store'>;
+/** Cuerpo de `POST /tenants/{slug}/transfer-ownership`: el usuario de la instancia que pasa a ser dueño. */
+export type TransferOwnershipRequest = Body<'tenant.transferOwnership'>;
+/**
+ * Cuerpo de `PUT /desarrollador/catalogo`: el catálogo del integrador ENTERO —
+ * cabecera (nombre comercial, soporte, moneda ISO 4217, enlace de contratación)
+ * y filas (`kind` ∈ `base|module|app`, `slug`, `price_cents` en subunidades de
+ * esa moneda, `contract_url` propio opcional, `enabled`)—. Lo que no venga deja
+ * de existir.
+ */
+export type CatalogoDelIntegradorRequest = Body<'integradorCatalogo.update'>;
+/**
+ * Cuerpo de `POST /desarrollador/tenants/{slug}/activaciones`: qué se activa al
+ * cliente (`kind` ∈ `base|module|app`, `slug`; `plan_id` solo si hay varios
+ * planes de canal).
+ */
+export type ActivacionMayoristaRequest = Body<'integradorActivacion.store'>;
+export type IntegradorDominioRequest = Body<'integradorDominio.store'>;
+export type IntegradorTokenRequest = Body<'integradorToken.store'>;
+export interface PimiaCentralClientOptions {
+    /** El ápice, sin `/api`: `https://pimia.es` (o `https://taskai.work` en dev). */
+    baseUrl: string;
+    /**
+     * El token personal de la cuenta de desarrollador, o una función que lo
+     * devuelva (para leerlo de un secreto en cada llamada). Se manda como
+     * `Authorization: Bearer`.
+     */
+    token: string | (() => string | Promise<string>);
+    /** `fetch` a usar (por defecto, el global). Útil para tests y proxies. */
+    fetch?: typeof globalThis.fetch;
+    /** Cabeceras fijas para todas las llamadas. */
+    headers?: Record<string, string>;
+}
+export interface CentralRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    query?: Record<string, string | number | boolean | undefined | null | Array<string | number>>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+export interface CentralResponseMeta {
+    status: number;
+    requestId?: string;
+}
+export interface CentralResponseWithMeta<T> {
+    data: T;
+    meta: CentralResponseMeta;
+}
+export declare class PimiaCentralClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly doFetch;
+    private readonly extraHeaders;
+    constructor(options: PimiaCentralClientOptions);
+    /** `GET /desarrollador/overview`: la cartera, con la atribución de cada alta. */
+    overview(): Promise<{
+        data: {
+            cartera: {
+                id: string;
+                name: string;
+                status: string;
+                plan: string | null;
+                created_at: string | null;
+                trial_ends_at: string | null;
+                relacion: string;
+                billing_mode: string | null;
+                la_pago_yo: boolean;
+                marca_blanca: boolean;
+                origen: {
+                    client_id: string;
+                    name: string;
+                    atribuido: boolean;
+                } | null;
+            }[];
+            resumen: {
+                total: number;
+                activos: number;
+                suspendidos: number;
+            };
+            cuota: {
+                usada: number;
+                limite: number;
+                ilimitada: boolean;
+            };
+        };
+    }>;
+    /** `GET /desarrollador/salud`: clients, webhooks y propuestas, solo los propios. */
+    salud(): Promise<{
+        data: {
+            clients: {
+                client_id: string;
+                name: string;
+                revoked_at: string | null;
+                tokens_vivos: number;
+                ultimo_uso: string | null;
+            }[];
+            webhooks: {
+                id: number;
+                tenant_id: string | null;
+                url: string;
+                events: string[];
+                disabled_at: string | null;
+                consecutive_failures: number;
+                entregas_7d: {
+                    delivered: number;
+                    pending: number;
+                    dead: number;
+                };
+            }[];
+            approvals: {
+                abiertas: number;
+                por_tenant: {
+                    tenant_id: string;
+                    abiertas: number;
+                }[];
+            };
+        };
+    }>;
+    /** `GET /desarrollador/facturacion`: lo que el integrador paga a Pimia (canal y asientos). */
+    facturacion(): Promise<{
+        data: {
+            canal: {
+                estado: string;
+                asientos: number;
+                quantity: number;
+                descuadre: boolean;
+                termina_en: string | null;
+            } | null;
+            asientos: {
+                tenant_id: string;
+                rol: string;
+                en_mora: boolean;
+                gracia_hasta: string | null;
+                suspendido_desde: string | null;
+            }[];
+            en_mora: number;
+            anadidos: {
+                activaciones: number;
+                total_cents: number;
+                total: string;
+                por_tenant: {
+                    tenant_id: string;
+                    activaciones: number;
+                    total_cents: number;
+                }[];
+            };
+        };
+    }>;
+    get links(): {
+        list: () => Promise<{
+            data: {
+                id: number;
+                link_code: string;
+                status: string;
+                tenant: {
+                    id: string;
+                    name: string;
+                    status: string;
+                } | null;
+                requester: {
+                    id: number;
+                    name: string;
+                    email: string;
+                } | null;
+                requested_at: string | null;
+                accepted_at: string | null;
+                revoked_at: string | null;
+                created_at: string | null;
+            }[];
+        }>;
+        /** Un código `DEV-XXXX-XXXX` que el cliente teclea en su instancia. */
+        generateCode: () => Promise<{
+            message: "C\u00F3digo de vinculaci\u00F3n generado.";
+            data: {
+                id: number;
+                link_code: string;
+                status: string;
+                tenant: {
+                    id: string;
+                    name: string;
+                    status: string;
+                } | null;
+                requester: {
+                    id: number;
+                    name: string;
+                    email: string;
+                } | null;
+                requested_at: string | null;
+                accepted_at: string | null;
+                revoked_at: string | null;
+                created_at: string | null;
+            };
+        }>;
+        accept: (id: number | string) => Promise<{
+            message: "Vinculaci\u00F3n aceptada.";
+            data: {
+                id: number;
+                link_code: string;
+                status: string;
+                tenant: {
+                    id: string;
+                    name: string;
+                    status: string;
+                } | null;
+                requester: {
+                    id: number;
+                    name: string;
+                    email: string;
+                } | null;
+                requested_at: string | null;
+                accepted_at: string | null;
+                revoked_at: string | null;
+                created_at: string | null;
+            };
+        }>;
+        reject: (id: number | string) => Promise<{
+            message: "Solicitud rechazada.";
+        }>;
+    };
+    get clients(): {
+        list: () => Promise<{
+            data: {
+                client_id: string;
+                name: string;
+                confidential: boolean;
+                scope: string;
+                registration_tenant_id: string;
+                revoked_at: string;
+                created_at: string;
+            }[];
+        }>;
+        /**
+         * Reclamar un client confidencial CON su secreto: la única prueba de
+         * propiedad que el núcleo acepta (RFC 7591). El secreto no se guarda.
+         */
+        claim: (body: Body<"desarrolladorLink.claimClient">) => Promise<{
+            message: string;
+        }>;
+    };
+    get catalogo(): {
+        /**
+         * `GET /desarrollador/catalogo`: el catálogo propio (`perfil`, `currency`,
+         * `items`) y lo que se puede revender (`disponibles`: Pimia base, los
+         * módulos opcionales ofrecidos y las apps integradas activas).
+         */
+        get: () => Promise<{
+            data: {
+                perfil: {
+                    nombre_comercial: string;
+                    soporte_url: string | null;
+                    soporte_email: string | null;
+                } | null;
+                currency: string | null;
+                contract_url: string | null;
+                items: {
+                    kind: string;
+                    slug: string;
+                    name: string;
+                    description: string | null;
+                    price_cents: number;
+                    price: string | null;
+                    contract_url: string | null;
+                    enabled: boolean;
+                }[];
+                disponibles: {
+                    base: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                    modules: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                    apps: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                };
+            };
+        }>;
+        /**
+         * `PUT /desarrollador/catalogo`: reemplaza el catálogo ENTERO. Es lo que
+         * el cliente del integrador ve en la pantalla de plan de su instancia en
+         * vez de los precios de Pimia; el precio es minorista y no toca el
+         * dinero de Pimia.
+         */
+        replace: (body: CatalogoDelIntegradorRequest) => Promise<{
+            data: {
+                perfil: {
+                    nombre_comercial: string;
+                    soporte_url: string | null;
+                    soporte_email: string | null;
+                } | null;
+                currency: string | null;
+                contract_url: string | null;
+                items: {
+                    kind: string;
+                    slug: string;
+                    name: string;
+                    description: string | null;
+                    price_cents: number;
+                    price: string | null;
+                    contract_url: string | null;
+                    enabled: boolean;
+                }[];
+                disponibles: {
+                    base: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                    modules: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                    apps: {
+                        slug: string;
+                        name: string;
+                        description: string | null;
+                        wholesale_price_cents: number | null;
+                        wholesale_price: string | null;
+                    }[];
+                };
+            };
+        }>;
+    };
+    get activaciones(): {
+        /**
+         * `GET /desarrollador/tenants/{slug}/activaciones`: la base (su asiento),
+         * los módulos y apps activos y lo que le cuestan al integrador al mes.
+         */
+        list: (tenantSlug: string) => Promise<{
+            data: {
+                base: {
+                    active: boolean;
+                    price_cents: number | null;
+                    price: string | null;
+                    plan: string | null;
+                };
+                items: {
+                    kind: string;
+                    slug: string;
+                    name: string;
+                    active_since: string;
+                    price_cents: number | null;
+                    price: string | null;
+                }[];
+                total_cents: number;
+                total: string;
+            };
+        }>;
+        /**
+         * `POST /desarrollador/tenants/{slug}/activaciones`: activar la base, un
+         * módulo o una app. La base es el asiento (la primera vez devuelve
+         * `checkout_url`); un módulo o una app exigen la base viva y se cobran
+         * al integrador como partida de su canal, sin prorrateo, en la factura
+         * del mes. Idempotente (`already_active`). Es lo que llama el webhook del
+         * integrador cuando su cliente le compra algo.
+         */
+        activate: (tenantSlug: string, body: ActivacionMayoristaRequest) => Promise<string | {
+            message: "Completa el alta de tu suscripci\u00F3n de canal para activar la licencia de este cliente." | "El cliente ya lo ten\u00EDa encendido por su cuenta: no se te cobra ni se le toca." | "Ya estaba activo." | "Activado: se cobra en tu canal desde la pr\u00F3xima factura.";
+            data: {
+                already_active: boolean;
+                inherited: boolean;
+                checkout_url: string | null;
+                quantity: number | null;
+                activation: {
+                    [key: string]: unknown;
+                } | null;
+            };
+        }>;
+        /**
+         * `DELETE /desarrollador/tenants/{slug}/activaciones/{kind}/{item}`: dar de
+         * baja. El módulo se apaga y deja de cobrarse; la app se desinstala de
+         * todas las empresas; la base suelta el asiento.
+         */
+        deactivate: (tenantSlug: string, kind: "base" | "module" | "app", item: string) => Promise<{
+            message: string;
+            data: {
+                quantity: number | null;
+            };
+        }>;
+    };
+    get dominios(): {
+        /** `GET /desarrollador/dominios`: sus nombres de login, con el `upstream` y el bloque de proxy de cada uno. */
+        list: () => Promise<{
+            data: {
+                slug: string;
+                host: string;
+                enabled: boolean;
+                login_url: string;
+                upstream: string;
+                proxy_secret: string;
+                proxy: string;
+                created_at: string | null;
+            }[];
+        }>;
+        /**
+         * `POST /desarrollador/dominios`: declarar el nombre público que el
+         * integrador sirve (`host`, p. ej. `login.erpstudio.es`) y su etiqueta
+         * interna (`slug`). Pimia no emite certificados ni toca DNS: devuelve
+         * `upstream` (`https://login-<slug>.<central>`), a donde su proxy tiene
+         * que reenviar con `Host` interno y el nombre público en
+         * `X-Forwarded-Host`, y `proxy`, el bloque de Caddy listo para pegar.
+         */
+        declare: (body: IntegradorDominioRequest) => Promise<{
+            message: "Nombre declarado. Apunta tu proxy al upstream y reenv\u00EDa el nombre p\u00FAblico en X-Forwarded-Host.";
+            data: {
+                slug: string;
+                host: string;
+                enabled: boolean;
+                login_url: string;
+                upstream: string;
+                proxy_secret: string;
+                proxy: string;
+                created_at: string | null;
+            };
+        }>;
+        /** `DELETE /desarrollador/dominios/{slug}`: retirar el nombre; el host interno deja de contestar. */
+        remove: (slug: string) => Promise<{
+            message: string;
+        }>;
+    };
+    get tokens(): {
+        /** `GET /desarrollador/tokens`: los tokens de máquina vivos (nunca los de una sesión del panel). */
+        list: () => Promise<{
+            data: {
+                id: number;
+                name: string;
+                abilities: string[];
+                last_used_at: string | null;
+                expires_at: string | null;
+                created_at: string | null;
+            }[];
+        }>;
+        /**
+         * `POST /desarrollador/tokens`: acuñar un token de máquina, acotado a la
+         * habilidad `desarrollador` y nada más. El token en claro (`data.token`)
+         * se devuelve UNA vez: guárdalo en tu servidor.
+         */
+        create: (body: IntegradorTokenRequest) => Promise<{
+            message: "Token creado. Gu\u00E1rdalo ahora: no se vuelve a ense\u00F1ar.";
+            data: {
+                token: string;
+                id: number;
+                name: string;
+                abilities: unknown[];
+                last_used_at: string | null;
+                expires_at: string | null;
+                created_at: string | null;
+            };
+        }>;
+        /** `DELETE /desarrollador/tokens/{id}`: revocarlo. */
+        revoke: (id: number | string) => Promise<{
+            message: string;
+        }>;
+    };
+    get invitations(): {
+        list: () => Promise<{
+            data: {
+                id: string;
+                email: string;
+                company_name: string;
+                billing: string;
+                status: string;
+                expires_at: string;
+                accepted_tenant_id: string;
+                accepted_at: string;
+                created_at: string;
+            }[];
+        }>;
+        /** El cliente se registra y nace dueño; `billing` dice quién paga. */
+        create: (body: TenantInvitationRequest) => Promise<{
+            message: string;
+            data: {
+                id: string;
+                email: string;
+                company_name: string;
+                billing: string;
+                status: string;
+                expires_at: string;
+                accepted_tenant_id: string;
+                accepted_at: string;
+                created_at: string;
+            };
+        }>;
+        revoke: (id: number | string) => Promise<{
+            message: "Invitaci\u00F3n revocada.";
+        }>;
+    };
+    get billing(): {
+        /**
+         * `POST /billing/portal` (1.4.0): la URL del portal de Stripe de la
+         * cuenta del integrador —las facturas del canal y el método de pago
+         * viven allí, no en Pimia—. 404 si la cuenta no tiene cliente de Stripe
+         * todavía (nunca patrocinó a nadie).
+         */
+        portal: (body?: BillingPortalRequest) => Promise<{
+            data: {
+                portal_url: string;
+            };
+        }>;
+    };
+    get sponsorship(): {
+        /** Asumir la licencia de un cliente: un asiento más en el plan de canal. */
+        sponsor: (body: SponsorshipRequest) => Promise<string | {
+            message: "Completa el alta de tu suscripci\u00F3n de canal para activar el patrocinio." | "Asumida la licencia de la instancia.";
+            data: {
+                checkout_url: string | null;
+            };
+        }>;
+        /** Soltar un cliente patrocinado (queda en gracia y puede rescatarse). */
+        release: (tenantSlug: string) => Promise<string | {
+            message: "Has dejado de pagar la licencia de esta instancia.";
+        }>;
+    };
+    get tenants(): {
+        /**
+         * `GET /tenants/{slug}/users` (1.4.0): quién pertenece a la instancia
+         * —nombre, correo, rol, `is_owner`—. Es a quién se le puede traspasar:
+         * `transferOwnership` pide el `user_id` de alguien que ya está dentro.
+         */
+        users: (slug: string) => Promise<{
+            data: {
+                id: number;
+                name: string;
+                email: string;
+                role: string;
+                invited_at: string | null;
+                is_owner: boolean;
+            }[];
+        }>;
+        /** Traspasar la propiedad de la instancia a un usuario de la misma, antes de entregarla. */
+        transferOwnership: (slug: string, body: TransferOwnershipRequest) => Promise<{
+            message: string;
+            data: {
+                tenant_id: string;
+                owner_id: number;
+                billing_mode: "sponsor" | "self";
+            };
+        }>;
+    };
+    request<T = unknown>(path: string, options?: CentralRequestOptions): Promise<T>;
+    requestWithMeta<T = unknown>(path: string, options?: CentralRequestOptions): Promise<CentralResponseWithMeta<T>>;
+    private urlFor;
+}
+export {};