@interware/content-generator 0.7.2 → 0.8.1

package/dist/server/src/drive/files.d.ts

@@ -0,0 +1,136 @@
+import type { DriveHttpClient } from './client';
+export declare const DRIVE_ROOT = "root";
+export declare const FOLDER_MIME = "application/vnd.google-apps.folder";
+export interface DriveFile {
+    id: string;
+    name: string;
+    mimeType: string;
+}
+type Http = Pick<DriveHttpClient, 'request'> & Partial<Pick<DriveHttpClient, 'download'>>;
+/** Resultado de subir: el id y el `md5Checksum` con el que Drive identifica esta versión del contenido. */
+export interface Uploaded {
+    id: string;
+    md5: string | null;
+}
+/** Un cambio de `changes.list` con los campos que usa la sincronización (S7.4). */
+export interface DriveChange {
+    fileId: string;
+    removed: boolean;
+    file?: {
+        id: string;
+        name: string;
+        mimeType: string;
+        parents?: string[];
+        trashed?: boolean;
+        md5Checksum?: string;
+        size?: string;
+    };
+}
+/** Literal de cadena para `q`: Drive escapa `\` y `'` con barra invertida. */
+export declare const quote: (value: string) => string;
+/** El elemento llamado `name` dentro de `parentId` (sin papelera), o `null`. */
+export declare const findChild: (http: Http, parentId: string, name: string) => Promise<DriveFile | null>;
+export declare const createFolder: (http: Http, parentId: string, name: string) => Promise<string>;
+/** Cuerpo `multipart/related` de Drive: metadatos JSON y contenido. */
+export declare const multipart: (metadata: Record<string, unknown>, mime: string, content: Uint8Array) => {
+    body: Buffer;
+    contentType: string;
+};
+export interface UploadInput {
+    name: string;
+    mime: string;
+    content: Uint8Array;
+    description?: string;
+}
+export declare const uploadFile: (http: Http, parentId: string, file: UploadInput) => Promise<Uploaded>;
+/** Contenido nuevo del mismo archivo de Drive: Drive guarda la versión anterior en su historial. */
+export declare const updateContent: (http: Http, driveId: string, file: UploadInput) => Promise<Uploaded>;
+/** Renombra y, si cambia `from` → `to`, mueve de carpeta. */
+export declare const updateMeta: (http: Http, driveId: string, { name, from, to }: {
+    name?: string;
+    from?: string;
+    to?: string;
+}) => Promise<void>;
+/** Manda a la papelera de Drive (se recupera durante 30 días). Si ya no existe, no es error. */
+export declare const trash: (http: Http, driveId: string) => Promise<void>;
+/** Contenido de un archivo binario de Drive. */
+export declare const download: (http: Http, driveId: string) => Promise<Uint8Array>;
+/** Elemento de la vista de Drive (S7.2). */
+export interface DriveEntry {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number | null;
+    modifiedTime: string | null;
+    webViewLink: string | null;
+    parents: string[];
+}
+/** Una página del contenido de una carpeta (sin papelera): carpetas primero, luego por nombre. */
+export declare const listChildren: (http: Http, parentId: string, pageToken?: string) => Promise<{
+    items: DriveEntry[];
+    nextPageToken: string;
+}>;
+export declare const getFile: (http: Http, id: string) => Promise<DriveEntry>;
+/** Cuántos archivos y carpetas hay dentro de una carpeta, recorriendo en vivo hasta `limit`. */
+export declare const countTree: (http: Http, folderId: string, limit?: number) => Promise<{
+    files: number;
+    folders: number;
+    truncated: boolean;
+}>;
+/**
+ * Estado actual de un archivo con los campos de `changes.list`, para la revisión completa contra Drive
+ * (S7.4). `null` si ya no existe.
+ */
+export declare const getMeta: (http: Http, id: string) => Promise<DriveChange['file'] | null>;
+/** Id real de «Mi unidad»: `changes.list` reporta los padres por id, no como `root`. */
+export declare const rootId: (http: Http) => Promise<string>;
+/** Token desde el que empezar a leer cambios: lo anterior no se procesa. */
+export declare const startPageToken: (http: Http) => Promise<string>;
+/** Una página de cambios del Drive desde `pageToken`. */
+export declare const listChanges: (http: Http, pageToken: string) => Promise<{
+    changes?: DriveChange[];
+    nextPageToken?: string;
+    newStartPageToken?: string;
+}>;
+/** Las operaciones de este módulo atadas a un cliente: el puerto que usan vínculos y sincronización. */
+export declare const driveOps: (http: Http) => {
+    findChild: (parentId: string, name: string) => Promise<DriveFile>;
+    createFolder: (parentId: string, name: string) => Promise<string>;
+    uploadFile: (parentId: string, file: UploadInput) => Promise<Uploaded>;
+    updateContent: (driveId: string, file: UploadInput) => Promise<Uploaded>;
+    updateMeta: (driveId: string, change: {
+        name?: string;
+        from?: string;
+        to?: string;
+    }) => Promise<void>;
+    trash: (driveId: string) => Promise<void>;
+    download: (driveId: string) => Promise<Uint8Array>;
+    startPageToken: () => Promise<string>;
+    rootId: () => Promise<string>;
+    listChildren: (parentId: string, pageToken?: string) => Promise<{
+        items: DriveEntry[];
+        nextPageToken: string;
+    }>;
+    getFile: (id: string) => Promise<DriveEntry>;
+    getMeta: (id: string) => Promise<{
+        id: string;
+        name: string;
+        mimeType: string;
+        parents?: string[];
+        trashed?: boolean;
+        md5Checksum?: string;
+        size?: string;
+    }>;
+    countTree: (folderId: string) => Promise<{
+        files: number;
+        folders: number;
+        truncated: boolean;
+    }>;
+    listChanges: (pageToken: string) => Promise<{
+        changes?: DriveChange[];
+        nextPageToken?: string;
+        newStartPageToken?: string;
+    }>;
+};
+export type DriveOps = ReturnType<typeof driveOps>;
+export {};

package/dist/server/src/drive/lifecycles.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vía rápida de la sincronización (ADR-009): los lifecycles de upload avisan que algo cambió en la
+ * Biblioteca. Solo encolan; la revisión de cada ciclo cubre lo que no pasa por aquí (`bulk-move`).
+ */
+import type { Core } from '@strapi/strapi';
+import type { CmsType } from './model';
+export declare const subscribeUploadLifecycles: (strapi: Core.Strapi, onChange: (cmsType: CmsType, cmsId: number) => Promise<void>) => void;

package/dist/server/src/drive/links.d.ts

@@ -0,0 +1,23 @@
+import type { DriveOps } from './files';
+import type { Cms, CmsFolder, CmsType, LinkRepo, OpQueue } from './model';
+export interface LinkDeps {
+    drive: DriveOps;
+    cms: Cms;
+    links: LinkRepo;
+    ops: OpQueue;
+}
+/**
+ * Carpetas entre «Generated» y el elemento, de arriba hacia abajo, sin incluir al elemento. `null` si no
+ * está dentro de «Generated».
+ */
+export declare const ancestorsOf: (cms: Cms, root: CmsFolder, path: string) => Promise<CmsFolder[] | null>;
+export declare const mark: (deps: LinkDeps, cmsType: CmsType, cmsId: number) => Promise<void>;
+/**
+ * Vínculos que siguen haciendo falta: los marcados, su contenido y los ancestros de cada marcado. Se calcula
+ * por rutas de Strapi (`path` / `folderPath`), sin recorrer el árbol.
+ */
+export declare const neededLinkIds: (deps: Pick<LinkDeps, 'cms' | 'links'>) => Promise<Set<number>>;
+/** Deja de sincronizar el elemento y su contenido. No borra nada en Drive ni en el CMS. */
+export declare const unmark: (deps: Pick<LinkDeps, 'cms' | 'links'>, cmsType: CmsType, cmsId: number) => Promise<void>;
+/** ¿El elemento queda dentro de algo marcado (él mismo o una carpeta superior)? */
+export declare const isSynced: (deps: Pick<LinkDeps, 'cms' | 'links'>, cmsType: CmsType, cmsId: number) => Promise<boolean>;

package/dist/server/src/drive/model.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Tipos de la sincronización con Drive (S7.3) y los puertos hacia Strapi (Biblioteca, vínculos, cola). Los
+ * adaptadores reales viven en `strapiPorts.ts`; las pruebas usan versiones en memoria.
+ */
+export type CmsType = 'file' | 'folder';
+export interface CmsFolder {
+    id: number;
+    pathId: number;
+    name: string;
+    /** Ruta de Strapi por `pathId`: `/44/45`. */
+    path: string;
+    parentId: number | null;
+}
+export interface CmsFile {
+    id: number;
+    name: string;
+    folderId: number | null;
+    /** `path` de su carpeta (`/44/45`), o `/` en la raíz. */
+    folderPath: string;
+    url: string;
+    /** KB, como lo guarda Strapi. */
+    size: number;
+    mime: string;
+}
+export type LinkStatus = 'synced' | 'pending' | 'error' | 'skipped';
+export interface DriveLink {
+    id: number;
+    cmsType: CmsType;
+    cmsId: number;
+    driveId: string | null;
+    root: boolean;
+    name: string | null;
+    parentCmsId: number | null;
+    version: string | null;
+    /** `md5Checksum` de Drive de la última versión sincronizada (S7.4); vacío en carpetas. */
+    driveRev: string | null;
+    status: LinkStatus;
+    error: string | null;
+}
+export type NewLink = Omit<DriveLink, 'id'>;
+export interface DriveOp {
+    id: number;
+    cmsType: CmsType;
+    cmsId: number;
+    attempts: number;
+    runAfter: number;
+    error: string | null;
+}
+/** La Biblioteca de Strapi (`plugin::upload.folder` y `plugin::upload.file`). */
+export interface Cms {
+    generatedRoot(): Promise<CmsFolder | null>;
+    folder(id: number): Promise<CmsFolder | null>;
+    file(id: number): Promise<CmsFile | null>;
+    foldersByPathIds(pathIds: number[]): Promise<CmsFolder[]>;
+    childFolders(folderId: number): Promise<CmsFolder[]>;
+    childFiles(folderId: number): Promise<CmsFile[]>;
+    readFile(file: CmsFile): Promise<Uint8Array>;
+}
+/** Escrituras a la Biblioteca para lo que llega de Drive (S7.4). Se hacen dentro de `withoutEcho`. */
+export interface CmsWriter {
+    uploadFile(folderId: number, name: string, mime: string, content: Uint8Array): Promise<CmsFile>;
+    replaceFile(id: number, name: string, mime: string, content: Uint8Array): Promise<CmsFile>;
+    updateFile(id: number, change: {
+        name?: string;
+        folderId?: number;
+    }): Promise<void>;
+    deleteFile(id: number): Promise<void>;
+    createFolder(name: string, parentId: number): Promise<CmsFolder>;
+    updateFolder(id: number, change: {
+        name?: string;
+        parentId?: number;
+    }): Promise<void>;
+    deleteFolder(id: number): Promise<void>;
+}
+export interface LinkRepo {
+    all(): Promise<DriveLink[]>;
+    find(cmsType: CmsType, cmsId: number): Promise<DriveLink | null>;
+    findByDriveId(driveId: string): Promise<DriveLink | null>;
+    create(data: NewLink): Promise<DriveLink>;
+    update(id: number, data: Partial<NewLink>): Promise<DriveLink>;
+    remove(id: number): Promise<void>;
+}
+export interface OpQueue {
+    /** Encola «revisa este elemento»; si ya está en cola, no duplica. */
+    push(cmsType: CmsType, cmsId: number): Promise<void>;
+    /** Hasta `limit` operaciones listas (`runAfter` vencido), las más viejas primero. */
+    ready(limit: number, now: number): Promise<DriveOp[]>;
+    done(op: DriveOp): Promise<void>;
+    retry(op: DriveOp, error: string, runAfter: number): Promise<void>;
+    count(): Promise<number>;
+}
+/** Entrada inválida o conflicto que el panel muestra tal cual. */
+export declare class DriveSyncError extends Error {
+    readonly status: 400 | 409;
+    constructor(message: string, status?: 400 | 409);
+}
+export declare const collisionMessage: (name: string) => string;
+/** Ids de carpeta (`pathId`) de una ruta de Strapi: `/44/45` → `[44, 45]`. */
+export declare const pathIds: (path: string) => number[];

package/dist/server/src/drive/oauth.d.ts

@@ -0,0 +1,47 @@
+/// <reference types="node" />
+import type { DriveClient } from './clientConfig';
+export declare const DRIVE_SCOPE = "https://www.googleapis.com/auth/drive";
+export declare const OAUTH_STATE_KEY = "DRIVE_OAUTH_STATE";
+export type Fetch = typeof fetch;
+/** Subconjunto del plugin store de Strapi que usa Drive. */
+export interface Store {
+    get: (p: {
+        key: string;
+    }) => Promise<unknown>;
+    set: (p: {
+        key: string;
+        value: unknown;
+    }) => Promise<void>;
+    delete: (p: {
+        key: string;
+    }) => Promise<void>;
+}
+/** Google rechazó las credenciales: código inválido, acceso revocado o token vencido. */
+export declare class DriveAuthError extends Error {
+    constructor(message: string);
+}
+export declare const authUrl: (client: DriveClient, redirectUri: string, state: string) => string;
+/** Emite un `state` de un solo uso que caduca en 10 minutos. */
+export declare const newState: (store: Store, now?: number) => Promise<string>;
+/** Verdadero si `state` es el último emitido y no ha caducado. Siempre lo consume. */
+export declare const checkState: (store: Store, state: unknown, now?: number) => Promise<boolean>;
+export declare const exchangeCode: ({ client, code, redirectUri, fetch: fetchFn, }: {
+    client: DriveClient;
+    code: string;
+    redirectUri: string;
+    fetch: Fetch;
+}) => Promise<{
+    accessToken: string;
+    expiresIn: number;
+    refreshToken: string;
+}>;
+export declare const refreshAccessToken: ({ client, refreshToken, fetch: fetchFn, }: {
+    client: DriveClient;
+    refreshToken: string;
+    fetch: Fetch;
+}) => Promise<{
+    accessToken: string;
+    expiresIn: number;
+}>;
+/** Revoca el token en Google. Un token ya inválido no es error: el resultado es el mismo. */
+export declare const revokeToken: (token: string, fetchFn: Fetch) => Promise<void>;

package/dist/server/src/drive/pull.d.ts

@@ -0,0 +1,23 @@
+import type { DriveChange } from './files';
+import type { CmsWriter } from './model';
+import type { SyncDeps } from './sync';
+export declare const PAGE_TOKEN_KEY = "DRIVE_PAGE_TOKEN";
+export declare const ROOT_ID_KEY = "DRIVE_ROOT_ID";
+/** Se hizo la revisión completa contra Drive desde el último punto de partida. */
+export declare const FULL_CHECK_KEY = "DRIVE_FULL_CHECK";
+export interface PullDeps extends SyncDeps {
+    writer: CmsWriter;
+}
+/** Aplica un cambio de Drive (tabla del diseño de S7.4). */
+/** Aplica un cambio de Drive. Verdadero si cambió algo (en el CMS o en los vínculos). */
+export declare const applyChange: (deps: PullDeps, change: DriveChange, rootId: string) => Promise<boolean>;
+/**
+ * Lee y aplica los cambios pendientes de Drive. Sin punto de partida, lo guarda y hace una revisión completa
+ * de lo vinculado, para no perder lo que cambió antes.
+ */
+export declare const pullChanges: (deps: PullDeps, { full }?: {
+    full?: boolean;
+}) => Promise<{
+    applied: number;
+    errors: number;
+}>;

package/dist/server/src/drive/strapiPorts.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import type { Core } from '@strapi/strapi';
+import type { Cms, CmsWriter, LinkRepo, OpQueue } from './model';
+export declare const LINK_UID = "plugin::strapi-content-generator-gemini.drive-link";
+export declare const OP_UID = "plugin::strapi-content-generator-gemini.drive-op";
+export declare const strapiCms: (strapi: Core.Strapi, fetchFn?: typeof fetch) => Cms;
+/** Escrituras con los servicios de `@strapi/upload`, para que rutas, formatos y proveedor (S3) sean los de Strapi. */
+export declare const strapiCmsWriter: (strapi: Core.Strapi) => CmsWriter;
+export declare const strapiLinks: (strapi: Core.Strapi) => LinkRepo;
+export declare const strapiOps: (strapi: Core.Strapi) => OpQueue;

package/dist/server/src/drive/sync.d.ts

@@ -0,0 +1,40 @@
+export { MAX_FILE_BYTES, isEcho, versionOf, withoutEcho } from './common';
+import type { LinkDeps } from './links';
+import type { CmsFile, CmsType, CmsWriter } from './model';
+import type { Store } from './oauth';
+export declare const LOCK_KEY = "DRIVE_LOCK";
+export declare const LAST_RUN_KEY = "DRIVE_LAST_RUN";
+export interface SyncDeps extends LinkDeps {
+    /** Lo que llega de Drive se escribe con esto (S7.4); sin él, el ciclo solo sube del CMS a Drive. */
+    writer?: CmsWriter;
+    store: Store;
+    now?: () => number;
+    /** Descripción del archivo en Drive (por ejemplo, el template de origen), si tiene. */
+    describe?: (file: CmsFile) => Promise<string | undefined>;
+    log?: {
+        warn: (msg: string) => void;
+        info?: (msg: string) => void;
+    };
+}
+export interface SyncSummary {
+    skipped: boolean;
+    /** Cambios de Drive aplicados al CMS (S7.4). */
+    pulled: number;
+    processed: number;
+    errors: number;
+    pending: number;
+}
+/** Decide y aplica lo que corresponde a un elemento (tabla del diseño de S7.3). */
+export declare const processItem: (deps: SyncDeps, cmsType: CmsType, cmsId: number, depth?: number) => Promise<void>;
+/**
+ * Compara lo vinculado con el CMS y encola lo que cambió, lo que se borró y lo que llegó a una carpeta
+ * sincronizada sin pasar por un lifecycle (`bulk-move`).
+ */
+export declare const reconcile: (deps: SyncDeps) => Promise<void>;
+/** Un ciclo completo: revisión y cola por tandas, con un solo proceso a la vez. */
+export declare const runSync: (deps: SyncDeps, { budgetMs, full }?: {
+    budgetMs?: number;
+    full?: boolean;
+}) => Promise<SyncSummary>;
+/** Programa un ciclo `delayMs` después de la última llamada (los lifecycles llegan en ráfagas). */
+export declare const debounce: (run: () => Promise<unknown>, delayMs?: number, onError?: (err: unknown) => void) => () => void;