@miguelmorales13/nestkit 0.8.0 → 0.10.0

package/README.md

@@ -578,6 +578,49 @@ El token se saca en developers.pinterest.com con los permisos `boards:read`,
 `pins:read` y `pins:write`. Los títulos se recortan a 100 caracteres y las
 descripciones a 800, que son los límites del API — pasarse devuelve un 400.
 
+### `tiktok` — publicar videos, y el modo que evita la auditoría
+
+Publicar son dos llamadas: inicializar la subida y sondear hasta que TikTok
+termine de procesar.
+
+```ts
+import { TikTokModule, TikTokService } from '@miguelmorales13/nestkit/tiktok';
+
+@Module({ imports: [TikTokModule.forRoot()] })   // lee TIKTOK_ACCESS_TOKEN
+export class AppModule {}
+```
+
+```ts
+await tiktok.userInfo();                          // comprueba el token sin publicar
+const id = await tiktok.publish({ data, title }); // sin privacyLevel: a borradores
+await tiktok.status(id);                          // hasta PUBLISH_COMPLETE
+```
+
+**Cuidado con `creatorInfo()`.** Parece el paso previo obligatorio —así lo
+sugiere la documentación— pero solo lo es para publicar **en directo**, y
+además exige `video.publish`. Llamarlo con un token de borradores devuelve
+`scope_not_authorized`, o sea que falla justo en la configuración más común.
+Para comprobar que el token vive, `userInfo()`, que se conforma con
+`user.info.basic`.
+
+**La diferencia entre los dos modos importa mucho al principio.** En *Direct
+Post* el video sale en vivo, pero exige el permiso `video.publish`, que solo se
+consigue pasando una auditoría de TikTok de varias semanas —y hasta aprobarla
+todo lo publicado queda en `SELF_ONLY`, o sea que no lo ve nadie—. En modo
+**borrador**, que es el de por defecto aquí, el video cae en la bandeja de la
+cuenta y una persona le da publicar desde el teléfono: llega con todo su
+alcance y solo necesita `video.upload`.
+
+Dicho de otro modo: publicar en directo antes de la auditoría es peor que no
+publicar, porque gastas la pieza sin que la vea nadie.
+
+Sube el binario en vez de pasar una URL a propósito. La otra vía,
+`PULL_FROM_URL`, obliga a verificar el dominio en el portal de TikTok, y
+cambiar un trámite por otro no compensa cuando el archivo ya está en disco.
+
+El video tiene que ir en **MP4 H.264**. Límite de **6 peticiones por minuto**
+por token, así que el sondeo del estado va espaciado.
+
 ### `stripe` — cliente de la SDK oficial
 
 ```ts
@@ -1023,6 +1066,7 @@ trae los datos.
 | `@miguelmorales13/nestkit/meta` | `MetaModule`, `MetaService` — publicar en Instagram y Facebook Pages |
 | `@miguelmorales13/nestkit/media` | `MediaModule`, `MediaService` — hosting efímero en memoria |
 | `@miguelmorales13/nestkit/pinterest` | `PinterestModule`, `PinterestService` — publicar pines |
+| `@miguelmorales13/nestkit/tiktok` | `TikTokModule`, `TikTokService` — publicar videos |
 | `@miguelmorales13/nestkit/stripe` | `StripeModule`, `STRIPE_CLIENT`, `createStripeWebhookController` |
 | `@miguelmorales13/nestkit/auth` | `AuthUserPort`, `BaseAuthService`, `createAuthController`, `TokenService`, `JwtAuthGuard`, `RolesGuard`, `RequireTenantGuard`, `CurrentUser`, `CurrentTenant`, `Roles` |
 | `@miguelmorales13/nestkit/auth/oauth` | `OAuthAuthModule`, `OAuthAuthService`, `createOAuthController`, `googleProvider`, `facebookProvider`, `OAuthStorePort`, `RefreshTokenStorePort` |
@@ -1033,9 +1077,13 @@ trae los datos.
 | `@miguelmorales13/nestkit/i18n` | `I18nModule` (wrapper de `nestjs-i18n`), `translateOr` |
 | `@miguelmorales13/nestkit/bootstrap` | `applyNestKitDefaults` |
 
+## Cambios recientes
+
+Qué se añadió en cada versión y por qué está hecho así: [CAMBIOS.md](./CAMBIOS.md).
+
 ## Estado del paquete
 
-`0.8.0`. Sin adaptador Mongo real. Sin tests unitarios propios.
+`0.10.0`. Sin adaptador Mongo real. Sin tests unitarios propios.
 
 `auth/oauth` y `umami` sí tienen un consumidor real: **nutrimx** corre su acceso con Google y
 Facebook sobre este módulo en producción. El resto sigue sin ejercitarse de verdad.

package/dist/index.cjs

@@ -28,6 +28,10 @@ var _chunk3CLYZC3Tcjs = require('./chunk-3CLYZC3T.cjs');
 
 
 var _chunkQS2W5XCQcjs = require('./chunk-QS2W5XCQ.cjs');
+
+
+
+var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
 require('./chunk-7SOM7EZP.cjs');
 
 
@@ -45,10 +49,6 @@ var _chunkZA56XBCKcjs = require('./chunk-ZA56XBCK.cjs');
 
 
 var _chunkR7BVS6CIcjs = require('./chunk-R7BVS6CI.cjs');
-
-
-
-var _chunkM3EL5O6Tcjs = require('./chunk-M3EL5O6T.cjs');
 require('./chunk-2REOCMUD.cjs');
 
 

package/dist/index.js

@@ -28,6 +28,10 @@ import {
 import {
   BaseResponseDto
 } from "./chunk-XX2HPTRU.js";
+import {
+  I18nModule,
+  translateOr
+} from "./chunk-IYUUYCP5.js";
 import "./chunk-DQYAIQQ5.js";
 import {
   ConflictAppException,
@@ -45,10 +49,6 @@ import {
 import {
   AppException
 } from "./chunk-YFYHLYHN.js";
-import {
-  I18nModule,
-  translateOr
-} from "./chunk-IYUUYCP5.js";
 import "./chunk-4MGIQFAJ.js";
 export {
   AppException,

package/dist/tiktok/index.cjs

@@ -0,0 +1,165 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+
+var _chunk2REOCMUDcjs = require('../chunk-2REOCMUD.cjs');
+
+// src/tiktok/tiktok.service.ts
+var _common = require('@nestjs/common');
+var API = "https://open.tiktokapis.com/v2";
+var TikTokService = class {
+  constructor(credentials) {
+    this.credentials = credentials;
+  }
+  get configured() {
+    return Boolean(this.credentials.accessToken);
+  }
+  /**
+   * Datos de la cuenta: qué niveles de privacidad admite —varían según si es
+   * privada, de empresa o de un menor— y cuánto puede durar el video.
+   *
+   * **Obligatorio solo para publicar en directo.** Para el modo borrador no
+   * hace falta, y llamarlo con un token que solo tiene `video.upload` falla
+   * con `scope_not_authorized`, porque este endpoint pide `video.publish`.
+   * De ahí que `publish()` solo lo consulte cuando va a publicar directo.
+   */
+  async creatorInfo() {
+    return this.request("/post/publish/creator_info/query/", {});
+  }
+  /**
+   * Sube un vídeo y devuelve el `publish_id` con el que seguir su estado.
+   *
+   * Sin `privacyLevel` va a borradores; con él, se publica directo —y para eso
+   * hace falta que la aplicación haya pasado la auditoría.
+   */
+  async publish(video) {
+    const directo = Boolean(video.privacyLevel);
+    const ruta = directo ? "/post/publish/video/init/" : "/post/publish/inbox/video/init/";
+    const cuerpo = {
+      source_info: {
+        source: "FILE_UPLOAD",
+        video_size: video.data.byteLength,
+        // Una sola parte: estos clips son de unos pocos megas y trocearlos
+        // solo añadiría puntos donde fallar.
+        chunk_size: video.data.byteLength,
+        total_chunk_count: 1
+      }
+    };
+    if (directo) {
+      cuerpo.post_info = {
+        title: video.title.slice(0, 2200),
+        privacy_level: video.privacyLevel
+      };
+    }
+    const inicio = await this.request(
+      ruta,
+      cuerpo
+    );
+    const subida = await fetch(inicio.upload_url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "video/mp4",
+        // TikTok exige el rango incluso subiendo el archivo entero de una vez.
+        "Content-Range": `bytes 0-${video.data.byteLength - 1}/${video.data.byteLength}`
+      },
+      body: new Uint8Array(video.data)
+    });
+    if (!subida.ok) {
+      throw new Error(
+        `TikTok rechaz\xF3 el archivo (HTTP ${subida.status}): ${(await subida.text()).slice(0, 200)}`
+      );
+    }
+    return inicio.publish_id;
+  }
+  /**
+   * Quién es el dueño del token.
+   *
+   * Sirve para comprobar que el token vive sin publicar nada: `creatorInfo`
+   * no vale para eso porque pide un permiso que un token de borradores no
+   * tiene. Solo necesita `user.info.basic`.
+   */
+  async userInfo() {
+    const datos = await this.get(
+      "/user/info/?fields=open_id,display_name"
+    );
+    return datos.user;
+  }
+  /** En qué va el procesado. Termina en `PUBLISH_COMPLETE` o en un fallo. */
+  async status(publishId) {
+    return this.request(
+      "/post/publish/status/fetch/",
+      { publish_id: publishId }
+    );
+  }
+  get(path) {
+    return this.llamar(path, "GET");
+  }
+  request(path, body) {
+    return this.llamar(path, "POST", body);
+  }
+  async llamar(path, method, body) {
+    if (!this.credentials.accessToken) {
+      throw new Error("TikTokService: no access token configured");
+    }
+    const response = await fetch(`${API}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.credentials.accessToken}`,
+        "Content-Type": "application/json; charset=UTF-8"
+      },
+      ...method === "POST" ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await response.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch (e) {
+      throw new Error(`TikTok respondi\xF3 ${response.status} y no era JSON: ${text.slice(0, 200)}`);
+    }
+    if (json.error && json.error.code && json.error.code !== "ok") {
+      throw new Error(`TikTok: ${json.error.code} \u2014 ${_nullishCoalesce(json.error.message, () => ( ""))}`.trim());
+    }
+    if (!response.ok) {
+      throw new Error(`TikTok respondi\xF3 HTTP ${response.status}: ${text.slice(0, 200)}`);
+    }
+    if (!json.data) {
+      throw new Error(`TikTok devolvi\xF3 una respuesta sin datos: ${text.slice(0, 200)}`);
+    }
+    return json.data;
+  }
+};
+TikTokService = exports.TikTokService = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
+  _common.Injectable.call(void 0, )
+], TikTokService);
+
+// src/tiktok/tiktok.module.ts
+
+var TikTokModule = class {
+  static forRoot(credentials) {
+    return {
+      module: TikTokModule,
+      providers: [
+        {
+          provide: TikTokService,
+          useFactory: () => {
+            const resolved = _nullishCoalesce(credentials, () => ( {
+              accessToken: _nullishCoalesce(process.env.TIKTOK_ACCESS_TOKEN, () => ( ""))
+            }));
+            if (!resolved.accessToken) {
+              throw new Error(
+                "TikTokModule: no access token. Set TIKTOK_ACCESS_TOKEN or pass credentials to forRoot()."
+              );
+            }
+            return new TikTokService(resolved);
+          }
+        }
+      ],
+      exports: [TikTokService]
+    };
+  }
+};
+TikTokModule = exports.TikTokModule = _chunk2REOCMUDcjs.__decorateClass.call(void 0, [
+  _common.Module.call(void 0, {})
+], TikTokModule);
+
+
+
+exports.TikTokModule = TikTokModule; exports.TikTokService = TikTokService;

package/dist/tiktok/index.d.ts

@@ -0,0 +1,3 @@
+export { TikTokService } from './tiktok.service.js';
+export type { TikTokCredentials, TikTokCreatorInfo, TikTokVideo, } from './tiktok.service.js';
+export { TikTokModule } from './tiktok.module.js';

package/dist/tiktok/index.js

@@ -0,0 +1,165 @@
+import {
+  __decorateClass
+} from "../chunk-4MGIQFAJ.js";
+
+// src/tiktok/tiktok.service.ts
+import { Injectable } from "@nestjs/common";
+var API = "https://open.tiktokapis.com/v2";
+var TikTokService = class {
+  constructor(credentials) {
+    this.credentials = credentials;
+  }
+  get configured() {
+    return Boolean(this.credentials.accessToken);
+  }
+  /**
+   * Datos de la cuenta: qué niveles de privacidad admite —varían según si es
+   * privada, de empresa o de un menor— y cuánto puede durar el video.
+   *
+   * **Obligatorio solo para publicar en directo.** Para el modo borrador no
+   * hace falta, y llamarlo con un token que solo tiene `video.upload` falla
+   * con `scope_not_authorized`, porque este endpoint pide `video.publish`.
+   * De ahí que `publish()` solo lo consulte cuando va a publicar directo.
+   */
+  async creatorInfo() {
+    return this.request("/post/publish/creator_info/query/", {});
+  }
+  /**
+   * Sube un vídeo y devuelve el `publish_id` con el que seguir su estado.
+   *
+   * Sin `privacyLevel` va a borradores; con él, se publica directo —y para eso
+   * hace falta que la aplicación haya pasado la auditoría.
+   */
+  async publish(video) {
+    const directo = Boolean(video.privacyLevel);
+    const ruta = directo ? "/post/publish/video/init/" : "/post/publish/inbox/video/init/";
+    const cuerpo = {
+      source_info: {
+        source: "FILE_UPLOAD",
+        video_size: video.data.byteLength,
+        // Una sola parte: estos clips son de unos pocos megas y trocearlos
+        // solo añadiría puntos donde fallar.
+        chunk_size: video.data.byteLength,
+        total_chunk_count: 1
+      }
+    };
+    if (directo) {
+      cuerpo.post_info = {
+        title: video.title.slice(0, 2200),
+        privacy_level: video.privacyLevel
+      };
+    }
+    const inicio = await this.request(
+      ruta,
+      cuerpo
+    );
+    const subida = await fetch(inicio.upload_url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "video/mp4",
+        // TikTok exige el rango incluso subiendo el archivo entero de una vez.
+        "Content-Range": `bytes 0-${video.data.byteLength - 1}/${video.data.byteLength}`
+      },
+      body: new Uint8Array(video.data)
+    });
+    if (!subida.ok) {
+      throw new Error(
+        `TikTok rechaz\xF3 el archivo (HTTP ${subida.status}): ${(await subida.text()).slice(0, 200)}`
+      );
+    }
+    return inicio.publish_id;
+  }
+  /**
+   * Quién es el dueño del token.
+   *
+   * Sirve para comprobar que el token vive sin publicar nada: `creatorInfo`
+   * no vale para eso porque pide un permiso que un token de borradores no
+   * tiene. Solo necesita `user.info.basic`.
+   */
+  async userInfo() {
+    const datos = await this.get(
+      "/user/info/?fields=open_id,display_name"
+    );
+    return datos.user;
+  }
+  /** En qué va el procesado. Termina en `PUBLISH_COMPLETE` o en un fallo. */
+  async status(publishId) {
+    return this.request(
+      "/post/publish/status/fetch/",
+      { publish_id: publishId }
+    );
+  }
+  get(path) {
+    return this.llamar(path, "GET");
+  }
+  request(path, body) {
+    return this.llamar(path, "POST", body);
+  }
+  async llamar(path, method, body) {
+    if (!this.credentials.accessToken) {
+      throw new Error("TikTokService: no access token configured");
+    }
+    const response = await fetch(`${API}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.credentials.accessToken}`,
+        "Content-Type": "application/json; charset=UTF-8"
+      },
+      ...method === "POST" ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await response.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`TikTok respondi\xF3 ${response.status} y no era JSON: ${text.slice(0, 200)}`);
+    }
+    if (json.error && json.error.code && json.error.code !== "ok") {
+      throw new Error(`TikTok: ${json.error.code} \u2014 ${json.error.message ?? ""}`.trim());
+    }
+    if (!response.ok) {
+      throw new Error(`TikTok respondi\xF3 HTTP ${response.status}: ${text.slice(0, 200)}`);
+    }
+    if (!json.data) {
+      throw new Error(`TikTok devolvi\xF3 una respuesta sin datos: ${text.slice(0, 200)}`);
+    }
+    return json.data;
+  }
+};
+TikTokService = __decorateClass([
+  Injectable()
+], TikTokService);
+
+// src/tiktok/tiktok.module.ts
+import { Module } from "@nestjs/common";
+var TikTokModule = class {
+  static forRoot(credentials) {
+    return {
+      module: TikTokModule,
+      providers: [
+        {
+          provide: TikTokService,
+          useFactory: () => {
+            const resolved = credentials ?? {
+              accessToken: process.env.TIKTOK_ACCESS_TOKEN ?? ""
+            };
+            if (!resolved.accessToken) {
+              throw new Error(
+                "TikTokModule: no access token. Set TIKTOK_ACCESS_TOKEN or pass credentials to forRoot()."
+              );
+            }
+            return new TikTokService(resolved);
+          }
+        }
+      ],
+      exports: [TikTokService]
+    };
+  }
+};
+TikTokModule = __decorateClass([
+  Module({})
+], TikTokModule);
+export {
+  TikTokModule,
+  TikTokService
+};

package/dist/tiktok/tiktok.module.d.ts

@@ -0,0 +1,13 @@
+import { type DynamicModule } from '@nestjs/common';
+import { type TikTokCredentials } from './tiktok.service.js';
+/**
+ * Outbound client for TikTok's Content Posting API. See `TikTokService`.
+ *
+ * Reads `TIKTOK_ACCESS_TOKEN` by default. Like `PinterestService`, the service
+ * takes plain credentials and uses nothing but `fetch`, so a script outside
+ * Nest can do `new TikTokService({ accessToken })` — which is what the caller
+ * holding the rendered video usually is.
+ */
+export declare class TikTokModule {
+    static forRoot(credentials?: TikTokCredentials): DynamicModule;
+}

package/dist/tiktok/tiktok.service.d.ts

@@ -0,0 +1,92 @@
+export interface TikTokCredentials {
+    /** Token de usuario con `video.upload` o `video.publish`. */
+    accessToken: string;
+}
+/** Lo que TikTok cuenta de la cuenta antes de dejar publicar. */
+export interface TikTokCreatorInfo {
+    creator_username: string;
+    creator_nickname: string;
+    /** Niveles de privacidad que la cuenta admite. Ver `publish`. */
+    privacy_level_options: string[];
+    max_video_post_duration_sec: number;
+}
+export interface TikTokVideo {
+    /** El vídeo, ya en MP4 H.264. */
+    data: Buffer;
+    /** El texto del post. Hasta 2200 caracteres. */
+    title: string;
+    /**
+     * Cómo queda publicado. Si se omite, va a **borradores**: aparece en la
+     * bandeja de TikTok de la cuenta y una persona le da publicar.
+     *
+     * Ese es el modo que conviene mientras la aplicación no haya pasado la
+     * auditoría de TikTok, porque el modo directo publica en `SELF_ONLY` hasta
+     * entonces —es decir, no lo ve nadie— mientras que el borrador llega igual
+     * y se publica a mano sin perder alcance.
+     */
+    privacyLevel?: string;
+}
+/**
+ * Publica vídeos con la Content Posting API de TikTok.
+ *
+ * Publicar son dos llamadas: inicializar la subida y sondear hasta que TikTok
+ * termine de procesar. Hay una tercera, `creatorInfo`, que es obligatoria
+ * **solo** para publicar en directo —y que además exige `video.publish`, así
+ * que llamarla con un token de borradores falla.
+ *
+ * **Dos modos, y la diferencia importa mucho al principio.** En *Direct Post*
+ * el vídeo sale en vivo, pero exige el permiso `video.publish`, que solo se
+ * consigue pasando una auditoría de TikTok de varias semanas; hasta aprobarla
+ * todo lo publicado queda en `SELF_ONLY` y no lo ve nadie. En modo *borrador*
+ * —el de por defecto aquí— el vídeo cae en la bandeja de la cuenta y una
+ * persona le da publicar desde el teléfono: llega con todo su alcance y solo
+ * necesita `video.upload`.
+ *
+ * Se sube el binario en vez de pasar una URL a propósito. La otra vía,
+ * `PULL_FROM_URL`, obliga a verificar el dominio en el portal de TikTok, y
+ * cambiar un trámite por otro no compensa cuando el archivo ya está en disco.
+ *
+ * El límite es de 6 peticiones por minuto y por token, así que el sondeo del
+ * estado va espaciado.
+ */
+export declare class TikTokService {
+    private readonly credentials;
+    constructor(credentials: TikTokCredentials);
+    get configured(): boolean;
+    /**
+     * Datos de la cuenta: qué niveles de privacidad admite —varían según si es
+     * privada, de empresa o de un menor— y cuánto puede durar el video.
+     *
+     * **Obligatorio solo para publicar en directo.** Para el modo borrador no
+     * hace falta, y llamarlo con un token que solo tiene `video.upload` falla
+     * con `scope_not_authorized`, porque este endpoint pide `video.publish`.
+     * De ahí que `publish()` solo lo consulte cuando va a publicar directo.
+     */
+    creatorInfo(): Promise<TikTokCreatorInfo>;
+    /**
+     * Sube un vídeo y devuelve el `publish_id` con el que seguir su estado.
+     *
+     * Sin `privacyLevel` va a borradores; con él, se publica directo —y para eso
+     * hace falta que la aplicación haya pasado la auditoría.
+     */
+    publish(video: TikTokVideo): Promise<string>;
+    /**
+     * Quién es el dueño del token.
+     *
+     * Sirve para comprobar que el token vive sin publicar nada: `creatorInfo`
+     * no vale para eso porque pide un permiso que un token de borradores no
+     * tiene. Solo necesita `user.info.basic`.
+     */
+    userInfo(): Promise<{
+        open_id: string;
+        display_name: string;
+    }>;
+    /** En qué va el procesado. Termina en `PUBLISH_COMPLETE` o en un fallo. */
+    status(publishId: string): Promise<{
+        status: string;
+        fail_reason?: string;
+    }>;
+    private get;
+    private request;
+    private llamar;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miguelmorales13/nestkit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -121,6 +121,11 @@
       "import": "./dist/pinterest/index.js",
       "require": "./dist/pinterest/index.cjs"
     },
+    "./tiktok": {
+      "types": "./dist/tiktok/index.d.ts",
+      "import": "./dist/tiktok/index.js",
+      "require": "./dist/tiktok/index.cjs"
+    },
     "./media": {
       "types": "./dist/media/index.d.ts",
       "import": "./dist/media/index.js",