@hed-hog/core 0.0.400 → 0.0.401

package/src/file/file.service.spec.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
-import { NotFoundException } from '@nestjs/common';
+import { NotFoundException, ServiceUnavailableException } from '@nestjs/common';
 import { FileService } from './file.service';
 import { ProviderFactory } from './provider/provider.factory';
 
@@ -274,6 +274,80 @@ describe('FileService — arquivo privado nas rotas por id', () => {
   });
 });
 
+/**
+ * Um 503 do Spaces com corpo que não é XML estourava no parse do SDK
+ * (`char 'u' is not expected`) e virava 500 na rota de segmento HLS. O SDK ainda
+ * carimba o status em `$metadata`, e é por ele que a falha vira 503 passageiro.
+ */
+describe('FileService — falha do storage na leitura', () => {
+  const buildService = (readError: unknown, size: number | null = 1024) => {
+    const prisma = {
+      file: {
+        findUnique: jest.fn().mockResolvedValue({
+          id: 9,
+          filename: 'seg037.ts',
+          location: 'lms/lessons/hls/2274/stream_0',
+          path: 'lms/lessons/hls/2274/stream_0/abc.ts',
+          size,
+          file_mimetype: { name: 'video/MP2T' },
+        } as never),
+      },
+    };
+    const service = new FileService(prisma as any, {} as any, {} as any, {} as any, {} as any);
+    const provider = {
+      metaData: jest.fn().mockResolvedValue({ ContentLength: 1024 } as never),
+      readStream: jest.fn().mockRejectedValue(readError as never),
+    };
+    jest.spyOn(service, 'getProvider').mockResolvedValue(provider as never);
+    return { service, provider };
+  };
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('503 do storage com corpo ilegível vira ServiceUnavailable com code STORAGE_UNAVAILABLE', async () => {
+    const sdkError = Object.assign(new Error("char 'u' is not expected.:1:1"), {
+      $metadata: { httpStatusCode: 503 },
+    });
+    const { service } = buildService(sdkError);
+
+    const erro: any = await service.openReadStreamById(9).catch((e) => e);
+
+    expect(erro).toBeInstanceOf(ServiceUnavailableException);
+    expect(erro.getResponse()).toMatchObject({ code: 'STORAGE_UNAVAILABLE' });
+    expect(erro.cause).toBe(sdkError);
+  });
+
+  it('throttle (SlowDown) também é indisponibilidade, inclusive na leitura por faixa', async () => {
+    const { service } = buildService(Object.assign(new Error('Slow down'), { name: 'SlowDown' }));
+
+    await expect(service.openReadStreamWithRange(9, 0, 99)).rejects.toBeInstanceOf(
+      ServiceUnavailableException,
+    );
+  });
+
+  it('NoSuchKey continua 404', async () => {
+    const { service } = buildService(Object.assign(new Error('missing'), { name: 'NoSuchKey' }));
+
+    await expect(service.openReadStreamById(9)).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it('erro sem status de storage é repassado como veio', async () => {
+    const original = new Error('boom');
+    const { service } = buildService(original);
+
+    await expect(service.openReadStreamById(9)).rejects.toBe(original);
+  });
+
+  it('não faz HEAD no storage quando o tamanho já está na tabela', async () => {
+    const { service, provider } = buildService(null);
+    provider.readStream.mockResolvedValue({} as never);
+
+    await service.openReadStreamById(9);
+
+    expect(provider.metaData).not.toHaveBeenCalled();
+  });
+});
+
 /**
  * A varredura de reotimização do acervo passa em todo arquivo, e recomprimir WebP sobre
  * WebP sempre devolve alguns bytes a menos. Sem um ganho mínimo, cada passada trocaria o
@@ -367,3 +441,96 @@ describe('FileService.reoptimizeFile — ganho mínimo', () => {
     expect(result.mimetypeChanged).toBe(true);
   });
 });
+
+/**
+ * O Instagram recusa WebP, e toda image/* que passa pela otimizacao vira WebP. Quem
+ * entrega o arquivo a um consumidor externo pede os bytes intactos.
+ */
+describe('FileService — skipImageOptimization', () => {
+  const makeService = () => {
+    const deps: any = {
+      prisma: { file: { create: jest.fn().mockImplementation((args: any) => Promise.resolve(args.data)) } },
+      pagination: {},
+      setting: {},
+      jwt: {},
+      imageOptimization: {
+        optimizeBuffer: jest.fn().mockResolvedValue({
+          buffer: Buffer.from('webp'),
+          mimetype: 'image/webp',
+          originalname: 'foto.webp',
+        } as never),
+      },
+    };
+    const service = new FileService(
+      deps.prisma,
+      deps.pagination,
+      deps.setting,
+      deps.jwt,
+      deps.imageOptimization,
+    );
+    const provider = {
+      upload: jest.fn().mockResolvedValue('social/foto.jpg' as never),
+      uploadFromPath: jest.fn().mockResolvedValue('social/foto.jpg' as never),
+    };
+    jest.spyOn(service as any, 'getProvider').mockResolvedValue(provider as never);
+    jest.spyOn(service as any, 'getMimeType').mockResolvedValue(7 as never);
+    return { service, deps, provider };
+  };
+
+  it('upload grava a imagem sem otimizar quando o chamador pede', async () => {
+    const { service, deps, provider } = makeService();
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 1, 2, 3]);
+
+    const file: any = await service.upload(
+      'social/brands/1',
+      { buffer: jpeg, mimetype: 'image/jpeg', originalname: 'foto.jpg', size: jpeg.length } as any,
+      undefined,
+      { skipMimeValidation: true, skipSizeValidation: true, skipImageOptimization: true },
+    );
+
+    expect(deps.imageOptimization.optimizeBuffer).not.toHaveBeenCalled();
+    const sent = (provider.upload.mock.calls[0] as any[])[1];
+    expect(sent.mimetype).toBe('image/jpeg');
+    expect(Buffer.compare(sent.buffer, jpeg)).toBe(0);
+    expect(file.size).toBe(jpeg.length);
+  });
+
+  it('upload sem a opcao continua otimizando', async () => {
+    const { service, deps } = makeService();
+    const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 1, 2, 3]);
+
+    await service.upload(
+      'social/brands/1',
+      { buffer: jpeg, mimetype: 'image/jpeg', originalname: 'foto.jpg', size: jpeg.length } as any,
+      undefined,
+      { skipMimeValidation: true, skipSizeValidation: true },
+    );
+
+    expect(deps.imageOptimization.optimizeBuffer).toHaveBeenCalledTimes(1);
+  });
+
+  it('uploadFromPath manda a imagem pelo caminho de streaming, intacta', async () => {
+    const { service, deps, provider } = makeService();
+    const os = await import('node:os');
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const tmp = path.join(os.tmpdir(), `skip-opt-${process.pid}.jpg`);
+    await fs.writeFile(tmp, Buffer.from([0xff, 0xd8, 0xff, 0xe0, 1, 2, 3]));
+
+    try {
+      await service.uploadFromPath('social/brands/1', tmp, {
+        mimetype: 'image/jpeg',
+        originalname: 'foto.jpg',
+        skipMimeValidation: true,
+        skipSizeValidation: true,
+        skipImageOptimization: true,
+      });
+    } finally {
+      await fs.rm(tmp, { force: true });
+    }
+
+    expect(deps.imageOptimization.optimizeBuffer).not.toHaveBeenCalled();
+    expect(provider.uploadFromPath).toHaveBeenCalledTimes(1);
+    expect(provider.upload).not.toHaveBeenCalled();
+  });
+});

package/src/file/file.service.ts

@@ -31,7 +31,8 @@ import {
   Injectable,
   Logger,
   NotFoundException,
-  OnModuleInit
+  OnModuleInit,
+  ServiceUnavailableException
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
 import { createHash } from 'crypto';
@@ -60,6 +61,9 @@ import {
 } from './provider/abstract.provider';
 import { ProviderFactory } from './provider/provider.factory';
 
+/** Códigos de erro do S3/Spaces que indicam indisponibilidade passageira, não arquivo ruim. */
+const STORAGE_UNAVAILABLE_CODES = ['SlowDown', 'ServiceUnavailable', 'InternalError', 'RequestTimeout'];
+
 type ResolvedProvider = {
   provider: AbstractProvider;
   providerId: number;
@@ -304,16 +308,37 @@ export class FileService implements OnModuleInit {
     return file;
   }
 
-  private mapStorageNotFoundError(error: any, fileId: number) {
-    const missingInStorage =
-      error?.name === 'NoSuchKey' ||
-      error?.Code === 'NoSuchKey' ||
-      error?.$metadata?.httpStatusCode === 404;
+  /**
+   * Traduz a falha do provider de storage para a resposta HTTP certa.
+   *
+   * 5xx e throttle do S3/Spaces são indisponibilidade passageira, não defeito:
+   * viram 503 com `code: STORAGE_UNAVAILABLE`, que o HttpExceptionFilter da API
+   * responde com `Retry-After` e reporta deduplicado. Sem isso, um 503 do Spaces
+   * com corpo que não é XML (ex.: `upstream connect error` do balanceador)
+   * estourava no parse do SDK como `char 'u' is not expected` e virava 500.
+   *
+   * O status vem de `$metadata.httpStatusCode`, que o SDK carimba mesmo quando a
+   * desserialização do erro falha; `$response.statusCode` cobre o resto.
+   */
+  private mapStorageError(error: any, fileId: number): never {
+    const status = error?.$metadata?.httpStatusCode ?? error?.$response?.statusCode;
+    const codes = [error?.name, error?.Code];
 
-    if (missingInStorage) {
+    if (codes.includes('NoSuchKey') || status === 404) {
       throw new NotFoundException(`File not found in storage: ${fileId}`);
     }
 
+    const unavailable =
+      (typeof status === 'number' && status >= 500) ||
+      codes.some((c) => STORAGE_UNAVAILABLE_CODES.includes(c));
+
+    if (unavailable) {
+      throw new ServiceUnavailableException(
+        { message: 'Storage temporarily unavailable', code: 'STORAGE_UNAVAILABLE' },
+        { cause: error },
+      );
+    }
+
     throw error;
   }
 
@@ -338,11 +363,15 @@ export class FileService implements OnModuleInit {
     const provider = await this.getProvider();
     const providerPath = this.resolveProviderPath(file);
 
+    // O HEAD só serve para descobrir o tamanho quando a tabela não o tem. Feito
+    // sempre, dobrava as requisições ao storage em cada segmento HLS.
     let metadata: any;
-    try {
-      metadata = await provider.metaData(providerPath);
-    } catch {
-      metadata = undefined;
+    if (file.size == null) {
+      try {
+        metadata = await provider.metaData(providerPath);
+      } catch {
+        metadata = undefined;
+      }
     }
 
     try {
@@ -353,7 +382,7 @@ export class FileService implements OnModuleInit {
         size: file.size ?? this.getFileSizeFromMetadata(metadata),
       };
     } catch (error) {
-      this.mapStorageNotFoundError(error, fileId);
+      this.mapStorageError(error, fileId);
     }
   }
 
@@ -375,10 +404,15 @@ export class FileService implements OnModuleInit {
     const resolvedEnd = end !== undefined ? end : totalSize > 0 ? totalSize - 1 : undefined;
     const hasRange = start !== undefined;
 
-    const stream = await provider.readStream(
-      providerPath,
-      hasRange ? { start: resolvedStart, end: resolvedEnd } : undefined,
-    );
+    let stream: Awaited<ReturnType<AbstractProvider['readStream']>>;
+    try {
+      stream = await provider.readStream(
+        providerPath,
+        hasRange ? { start: resolvedStart, end: resolvedEnd } : undefined,
+      );
+    } catch (error) {
+      this.mapStorageError(error, fileId);
+    }
 
     const contentLength =
       resolvedEnd !== undefined ? resolvedEnd - resolvedStart + 1 : totalSize;
@@ -461,16 +495,7 @@ export class FileService implements OnModuleInit {
     try {
       providerBuffer = await provider.buffer(providerPath);
     } catch (error: any) {
-      const missingInStorage =
-        error?.name === 'NoSuchKey' ||
-        error?.Code === 'NoSuchKey' ||
-        error?.$metadata?.httpStatusCode === 404;
-
-      if (missingInStorage) {
-        throw new NotFoundException(`File not found in storage: ${fileId}`);
-      }
-
-      throw error;
+      this.mapStorageError(error, fileId);
     }
 
     const buffer = Buffer.from(providerBuffer);
@@ -549,6 +574,10 @@ export class FileService implements OnModuleInit {
       // Quem enviou. É o que permite recusar um `fileId` de outro usuário nas tools MCP
       // (ver `assertFileUsable`); fica nulo nos caminhos internos sem usuário.
       createdByUserId?: number | null;
+      // Grava a imagem byte a byte, sem a conversão para WebP nem o redimensionamento.
+      // Para quem entrega o arquivo a um consumidor externo que exige o formato
+      // original — o Instagram recusa WebP. O chamador já normalizou o arquivo.
+      skipImageOptimization?: boolean;
     },
   ) {
 
@@ -585,12 +614,18 @@ export class FileService implements OnModuleInit {
       fileBuffer.buffer,
     );
 
-    const optimized = await this.imageOptimizationService.optimizeBuffer(
-      fileBuffer.buffer,
-      effectiveMimetype,
-      normalizedFilename,
-      { maxWidth: resize?.maxWidth, maxHeight: resize?.maxHeight },
-    );
+    const optimized = options?.skipImageOptimization
+      ? {
+          buffer: fileBuffer.buffer,
+          mimetype: effectiveMimetype,
+          originalname: normalizedFilename,
+        }
+      : await this.imageOptimizationService.optimizeBuffer(
+          fileBuffer.buffer,
+          effectiveMimetype,
+          normalizedFilename,
+          { maxWidth: resize?.maxWidth, maxHeight: resize?.maxHeight },
+        );
 
     const normalizedFile = {
       ...fileBuffer,
@@ -635,6 +670,8 @@ export class FileService implements OnModuleInit {
       createdByUserId?: number | null;
       // Mesmo par maxWidth/maxHeight que `upload` aceita — só tem efeito em image/*.
       resize?: { maxWidth?: number; maxHeight?: number };
+      // Mesma opção de `upload`: a imagem segue o caminho de streaming, intacta.
+      skipImageOptimization?: boolean;
     },
   ) {
     if (!filePath) {
@@ -684,8 +721,9 @@ export class FileService implements OnModuleInit {
     // streaming direto do disco via provider.uploadFromPath. Isso evita carregar
     // o arquivo inteiro na RAM (fs.readFile estoura o limite de Buffer / causa OOM)
     // e habilita upload multipart no S3. A otimização de imagem só se aplica a
-    // image/*, então não há perda nesse caminho.
-    if (!mimetype.startsWith('image/')) {
+    // image/*, então não há perda nesse caminho. `skipImageOptimization` manda a
+    // imagem pelo mesmo caminho: o chamador quer os bytes exatamente como estão.
+    if (!mimetype.startsWith('image/') || metadata?.skipImageOptimization) {
       const url = await provider.uploadFromPath(destination, filePath, {
         filename: originalname,
         mimetype,

package/src/file/mcp-file-source.schema.ts

@@ -35,7 +35,7 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
   uploadId: {
     type: 'number',
     description:
-      'ID returned by core.files.create-upload-url or core.files.upload.init, after the binary has been uploaded. Use this to send a file that is on disk without putting its bytes in the conversation.',
+      'ID returned by core.files.create-upload-url (after the PUT) or core.files.upload.init (after every chunk was sent with core.files.upload.append). The upload is completed automatically, so core.files.upload.complete is optional here.',
   },
   fileUrl: {
     type: 'string',
@@ -45,7 +45,7 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
   fileBase64: {
     type: 'string',
     description:
-      'Base64-encoded content, sent inline. Only for small files (about 256kb): base64 of anything larger overflows the model output limit. Requires fileName and mimeType.',
+      'Base64-encoded content, sent inline. Only for small files (about 256kb): base64 of anything larger overflows the model output limit; use core.files.upload.init for larger files instead of giving up. Requires fileName and mimeType.',
   },
   fileName: {
     type: 'string',
@@ -72,9 +72,12 @@ export const FILE_SOURCE_SCHEMA_PROPERTIES: Record<string, any> = {
  * `storage-max-size`, e é ele que aparece na mensagem de erro.
  */
 export const FILE_SOURCE_DESCRIPTION = [
-  'Exactly one file source is required: fileId, uploadId, fileUrl or fileBase64.',
-  'Prefer fileId; use fileBase64 only for files of a few hundred kilobytes, since the encoded content has to fit in a single tool call.',
-  'To send a local file without putting it in the conversation, call core.files.create-upload-url, PUT the binary to the URL it returns, call core.files.upload.complete, and pass the resulting fileId here.',
+  'Exactly one file source is required: fileId, uploadId, fileUrl or fileBase64. Pick the first that fits:',
+  '(1) file already in storage: fileId.',
+  '(2) file publicly reachable on the internet: fileUrl.',
+  '(3) client can make HTTP requests to the Hub API host (e.g. a local CLI agent): core.files.create-upload-url, PUT the bytes to the returned url, then pass the uploadId (or the fileId from core.files.upload.complete). Fastest.',
+  '(4) client runs in a network-restricted sandbox (e.g. claude.ai), or the PUT fails with host_not_allowed, 403 or a network error: core.files.upload.init, then core.files.upload.append for each chunk (index 0..totalChunks-1, chunkBase64 of at most chunkBytes raw bytes as returned by init), then pass the uploadId (or the fileId from core.files.upload.complete). Nothing leaves the MCP connection, and it works up to the storage max size; generate the chunks programmatically in the sandbox (split the file, print the base64 of each chunk) instead of typing base64 by hand.',
+  '(5) small file (about 256kb or less): fileBase64 inline.',
   'Every path enforces the storage-accept-mimetype and storage-max-size settings (10mb by default).',
 ].join(' ');
 

package/src/index.ts

@@ -33,6 +33,9 @@ export * from './mail-layout/mail-layout.service';
 export * from './message-template/message-template.module';
 export * from './message-template/message-template.registry';
 export * from './message-template/message-template.service';
+export * from './document-kit/document-kit.module';
+export * from './document-kit/document-kit.registry';
+export * from './document-kit/document-kit.service';
 export * from './mail/mail.module';
 export * from './mail/mail.service';
 
@@ -57,8 +60,10 @@ export * from './file/mcp-file-source.schema';
 export * from './file/mimetype-sniff.util';
 export * from './file/remote-fetch.util';
 
+export * from './pdf/document';
 export * from './pdf/pdf.module';
 export * from './pdf/pdf.service';
+export * from './pdf/templates/commercial-proposal.template';
 export * from './setting/brand-asset.service';
 export * from './setting/setting.module';
 export * from './setting/setting.service';

package/src/integration-profile/integration-profile.secrets.ts

@@ -76,6 +76,27 @@ export const INTEGRATION_SECRET_KEYS: Record<string, string[]> = {
   // uso, então ele é reescrito no perfil a cada renovação: se não estiver aqui,
   // cada renovação grava a credencial em texto puro no banco.
   'melhor-envio': ['access_token', 'client_secret', 'refresh_token'],
+  // Redes sociais
+  // O app_secret troca o code do OAuth por token de qualquer Pagina que autorize o
+  // app; o webhook_verify_token e comparado no handshake dos webhooks da Meta.
+  // Os tokens das contas conectadas NAO moram aqui (ficam cifrados em
+  // social_channel, uma linha por Pagina/conta).
+  'meta-social': ['app_secret', 'webhook_verify_token'],
+  // App do Instagram (Instagram API with Instagram Login) — o segredo do app do
+  // INSTAGRAM, nao o do app da Meta. Troca o code do OAuth pelo token de
+  // qualquer conta que autorize o app; os tokens de 60 dias das contas ficam
+  // cifrados em social_channel.
+  'instagram-social': ['app_secret'],
+  // Apps do Google para o modulo social (um projeto por rede). O client_secret
+  // troca o code do OAuth pelo refresh token de qualquer canal/local que
+  // autorize o app; os refresh tokens ficam cifrados em social_channel.
+  'youtube-social': ['client_secret'],
+  'google-business-social': ['client_secret'],
+  // App do LinkedIn para paginas de empresa (Community Management API). O
+  // client_secret troca o code do OAuth e renova o access token de qualquer
+  // pagina que autorize o app; as credenciais das paginas (envelope lir1:/lia1:)
+  // ficam cifradas em social_channel.
+  'linkedin-social': ['client_secret'],
 };
 
 /** Chaves sensíveis de um provider (vazio se desconhecido). */

package/src/integration-profile/testers/ai.testers.ts

@@ -3,11 +3,45 @@ import {
   fail,
   pass,
   probeJson,
+  redactSecrets,
   requireFields,
   str,
+  type ProbeResult,
 } from './http-probe';
 import { IntegrationTester } from './integration-tester.types';
 
+/**
+ * A frase do veredito mais o que o provider de fato respondeu.
+ *
+ * Sem isso todo 401 virava a mesma sentenca fixa e a resposta do provider —
+ * que o `probeJson` ja captura — era jogada fora. Foi o que fez um header de
+ * organizacao errado ser reportado como "chave invalida", mandando conferir o
+ * campo que estava certo.
+ *
+ * O resultado de um tester NAO passa por `sanitizeTesterError` (esse so cobre o
+ * caminho de excecao), entao a redacao dos segredos acontece aqui.
+ */
+function withProviderDetail(
+  base: string,
+  result: ProbeResult,
+  secretValues: string[],
+): string {
+  const raw = String(result.body?.error?.message ?? '').trim();
+  if (!raw) return base;
+
+  const detail = redactSecrets(raw, secretValues).trim();
+  return detail ? `${base} ${detail}` : base;
+}
+
+/** O 401 da OpenAI culpa a chave ou a organizacao? A resposta dela ja diz. */
+function isOpenAiOrganizationProblem(result: ProbeResult): boolean {
+  const code = String(result.body?.error?.code ?? '');
+  const message = String(result.body?.error?.message ?? '');
+  return (
+    code === 'invalid_organization' || /no such organization/i.test(message)
+  );
+}
+
 /**
  * Testadores dos providers de IA e geração de vídeo.
  *
@@ -33,7 +67,26 @@ const openAiTester: IntegrationTester = {
       ctx.signal,
     );
 
-    if (result.status === 401) return fail('Invalid OpenAI API key.');
+    if (result.status === 401) {
+      // O header de organizacao e opcional e so este testador o envia: o chat
+      // real nunca manda. Apontar o campo certo evita trocar uma chave boa.
+      if (isOpenAiOrganizationProblem(result)) {
+        return fail(
+          withProviderDetail(
+            organization
+              ? `OpenAI rejected the organization "${organization}". ` +
+                'Check the Organization ID field (it looks like "org-..."), ' +
+                'or leave it empty.'
+              : 'OpenAI rejected the organization.',
+            result,
+            ctx.secretValues,
+          ),
+        );
+      }
+      return fail(
+        withProviderDetail('Invalid OpenAI API key.', result, ctx.secretValues),
+      );
+    }
     if (result.status === 403) {
       return fail('This API key has no permission to list models.');
     }
@@ -72,7 +125,9 @@ const geminiTester: IntegrationTester = {
     const result = await probeJson(url, {}, ctx.signal);
 
     if (result.status === 400 || result.status === 401 || result.status === 403) {
-      return fail('Invalid Gemini API key.');
+      return fail(
+        withProviderDetail('Invalid Gemini API key.', result, ctx.secretValues),
+      );
     }
     if (!result.ok) {
       return fail(describeHttpError(result, 'Google rejected the credentials.'));
@@ -102,7 +157,11 @@ const claudeTester: IntegrationTester = {
       ctx.signal,
     );
 
-    if (result.status === 401) return fail('Invalid Anthropic API key.');
+    if (result.status === 401) {
+      return fail(
+        withProviderDetail('Invalid Anthropic API key.', result, ctx.secretValues),
+      );
+    }
     if (!result.ok) {
       return fail(describeHttpError(result, 'Anthropic rejected the credentials.'));
     }
@@ -124,7 +183,11 @@ const deepseekTester: IntegrationTester = {
       ctx.signal,
     );
 
-    if (result.status === 401) return fail('Invalid DeepSeek API key.');
+    if (result.status === 401) {
+      return fail(
+        withProviderDetail('Invalid DeepSeek API key.', result, ctx.secretValues),
+      );
+    }
     if (!result.ok) {
       return fail(describeHttpError(result, 'DeepSeek rejected the credentials.'));
     }
@@ -147,7 +210,9 @@ const lumaTester: IntegrationTester = {
     );
 
     if (result.status === 401 || result.status === 403) {
-      return fail('Invalid Luma API key.');
+      return fail(
+        withProviderDetail('Invalid Luma API key.', result, ctx.secretValues),
+      );
     }
     if (!result.ok) {
       return fail(describeHttpError(result, 'Luma rejected the credentials.'));

package/src/integration-profile/testers/remaining.testers.spec.ts

@@ -26,11 +26,14 @@ const all = [
 const bySlug = (slug: string): IntegrationTester =>
   all.find((tester) => tester.providerSlug === slug)!;
 
-const ctx = (): IntegrationTestContext => ({
+const ctx = (
+  overrides: Partial<IntegrationTestContext> = {},
+): IntegrationTestContext => ({
   signal: AbortSignal.timeout(5_000),
   typeSlug: 'test',
   providerSlug: 'test',
   secretValues: [],
+  ...overrides,
 });
 
 function jsonResponse(body: unknown, status = 200) {
@@ -252,6 +255,67 @@ describe('openai tester', () => {
       error: 'Invalid OpenAI API key.',
     });
   });
+
+  // O header de organização é opcional e só este testador o envia. Um `org-...`
+  // errado devolve 401, e a mensagem fixa de "chave inválida" mandava conferir
+  // justamente o campo que estava certo.
+  it('culpa a organização, e não a chave, quando é ela que a OpenAI recusa', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        {
+          error: {
+            message: 'No such organization: org-errada.',
+            code: 'invalid_organization',
+          },
+        },
+        401,
+      ),
+    );
+
+    const outcome = await tester.test(
+      { api_key: 'sk-test', organization: 'org-errada' },
+      ctx(),
+    );
+
+    expect(outcome.ok).toBe(false);
+    expect(outcome.error).toContain('organization');
+    expect(outcome.error).toContain('org-errada');
+    expect(outcome.error).not.toContain('Invalid OpenAI API key');
+  });
+
+  it('acrescenta o motivo que a OpenAI deu quando a chave é mesmo o problema', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        { error: { message: 'Incorrect API key provided.', code: 'invalid_api_key' } },
+        401,
+      ),
+    );
+
+    const outcome = await tester.test({ api_key: 'sk-bad' }, ctx());
+
+    expect(outcome.error).toBe(
+      'Invalid OpenAI API key. Incorrect API key provided.',
+    );
+  });
+
+  // O resultado de um tester não passa por `sanitizeTesterError`, então a
+  // redação do segredo tem de acontecer dentro do próprio testador.
+  it('não deixa a chave vazar pela mensagem do provider', async () => {
+    fetchMock.mockResolvedValue(
+      jsonResponse(
+        { error: { message: 'Incorrect API key provided: sk-supersecreta.' } },
+        401,
+      ),
+    );
+
+    const outcome = await tester.test(
+      { api_key: 'sk-supersecreta' },
+      ctx({ secretValues: ['sk-supersecreta'] }),
+    );
+
+    expect(outcome.error).not.toContain('sk-supersecreta');
+    expect(outcome.error).toContain('***');
+  });
 });
 
 describe('claude tester', () => {

package/src/integration-profile/testers/tester-coverage.spec.ts

@@ -15,6 +15,16 @@ const EXTERNAL_PROVIDERS = new Set([
   // Abrir o certificado A1 é código do domínio fiscal: o tester se registra pelo
   // NfseNationalModule (libraries/fiscal).
   'nfse-national',
+  // App da Meta para redes sociais: o tester se registra pelo SocialModule
+  // (libraries/social), junto do client da Graph API.
+  'meta-social',
+  // App do Instagram (Instagram Login): o tester vive em libraries/social.
+  'instagram-social',
+  // Apps do Google do modulo social: os testers vivem em libraries/social.
+  'youtube-social',
+  'google-business-social',
+  // App do LinkedIn (paginas de empresa): o tester vive em libraries/social.
+  'linkedin-social',
 ]);
 
 /** Providers legítimos sem nenhum campo secreto. */