@pdf123/sdk: SDK TypeScript dla PDF123

Jak zainstalować SDK?#

Zainstaluj pakiet menedżerem pakietów. Wymagany jest Node 20.3 lub nowszy, Bun albo bundler. Typy TypeScript są dołączone, a @types/node nie jest potrzebne.

npm install @pdf123/sdk

bun add @pdf123/sdk i pnpm add @pdf123/sdk działają tak samo.

Jak połączyć dwa pliki PDF?#

Utwórz klienta, uruchom narzędzie merge na dwóch plikach i zapisz wynik. Bez opcji klient łączy się z publicznym API anonimowo.

import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
const path = await saveResult(result, { output: "merged.pdf" });
console.log(path);

Wynik zawiera bajty w data, contentType, nazwę pliku filename nadaną przez serwer oraz json dla narzędzi, które zwracają raport. Ta sama operacja jest dostępna w serwisie jako Połącz PDF.

Który punkt wejścia zaimportować?#

W przeglądarkach i środowiskach edge importuj z głównego punktu wejścia, a punkt node dodawaj tylko tam, gdzie czytasz lub zapisujesz pliki.

Jakie metody ma klient?#

Funkcje pomocnicze katalogu to zwykłe funkcje: TOOLS wymienia wszystkie narzędzia, getTool(id) zwraca pola, wartości domyślne i akceptowane typy plików jednego narzędzia, a toolGroup, toolSummary, matchesQuery i suggestTools pomagają budować selektory narzędzi. Wiersz poleceń wypisuje ten sam katalog poleceniami pdfx list i pdfx describe.

Jak przekazać opcje do narzędzia?#

params jest typowane dla każdego narzędzia. Przyjmuje tylko pola tego narzędzia, a pola wyboru akceptują tylko dozwolone wartości. Pola liczbowe są sprawdzane względem minimum i maksimum, a plik względem akceptowanych typów, zanim cokolwiek zostanie wysłane. Wartości domyślne potrzebne serwerowi są uzupełniane.

const marked = await client.run("watermark", {
  input: await readFileInput("a.pdf"),
  params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });

Pusty ciąg znaków oznacza „nie ustawiono”, więc obowiązuje wartość domyślna. Co robi każda opcja, opisuje strona Znak wodny PDF.

Jak przetworzyć wiele plików?#

runBatch uruchamia narzędzie jednoplikowe, na przykład Kompresuj, Obróć lub Zabezpiecz, na każdym wejściu z tymi samymi opcjami. Domyślnie przetwarza dwa pliki naraz. Jeden zły plik nigdy nie zatrzymuje pozostałych.

import { fileSource, saveResult } from "@pdf123/sdk/node";

const controller = new AbortController();
const entries = await client.runBatch("compress", [fileSource("a.pdf"), fileSource("b.pdf")], {
  concurrency: 2,
  signal: controller.signal,
  onResult: async (entry, index) => {
    if (entry.ok) await saveResult(entry.result, { output: "compressed/" });
  },
});
console.log(entries.map((entry) => entry.ok));

• fileSource(path) to leniwe źródło, które jest odczytywane dopiero wtedy, gdy przejmie je proces roboczy, więc wiele dużych plików nigdy nie leży w pamięci jednocześnie.
• onResult otrzymuje każdy wynik zaraz po zakończeniu. Zapisz go tam, a po anulowaniu przy pliku 50 ze 100 zachowasz pierwsze 49. Z retainData: false zwrócona tablica nie przechowuje bajtów.
• Każde wywołanie przyjmuje timeoutMs i signal, aby je anulować.
• idempotencyKey przyjmuje dla każdego pliku postać <key>:<index>.

Narzędzia filtrujące (identyfikatory zaczynające się od filter-) zwracają matched: false zamiast rzucać wyjątek, gdy ich warunek nie jest spełniony. W partii taki plik nadal liczy się jako ok.

Jak połączyć narzędzia w jednym żądaniu?#

pipeline wysyła listę kroków i jedno lub więcej wejść. Serwer przekazuje wynik każdego kroku do następnego.

const piped = await client.pipeline(
  [{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
  [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
await saveResult(piped, { output: "out.pdf" });

Potoki przyjmują te same opcje haseł co run.

Jak pracować z zaszyfrowanymi plikami PDF?#

Przekaż password do run, aby najpierw otworzyć zaszyfrowane wejście. Odblokowanie i uruchomienie narzędzia odbywają się w jednym żądaniu. Dla narzędzi przyjmujących wiele plików, takich jak Połącz, przekaż passwords z jednym wpisem na wejście, używając pustego ciągu dla pliku otwartego. Każdy plik jest odblokowywany osobno.

await client.run("compress", { input: await readFileInput("locked.pdf"), password: "secret" });
await client.run("merge", {
  input: [await readFileInput("locked.pdf"), await readFileInput("open.pdf")],
  passwords: ["secret", ""],
});

W partii passwordFor(file, index) zwraca hasło dla każdego wejścia. Aby trwale usunąć ochronę, użyj narzędzia Odblokuj.

Jak działają błędy?#

Błędy rzucają Pdf123Error. Ma on status (undefined, gdy nie było odpowiedzi), code, reason ze szczegółową przyczyną, na przykład password_required, oraz problem ze szczegółami problemu zwróconymi przez serwer, które zawierają hint, jeśli jest dostępna. Błędy walidacji są rzucane, zanim cokolwiek zostanie wysłane.

import { Pdf123Error } from "@pdf123/sdk";

try {
  await client.run("compress", { input: await readFileInput("locked.pdf") });
} catch (error) {
  if (error instanceof Pdf123Error) {
    console.error(error.status, error.code, error.reason, error.problem?.hint);
  } else {
    throw error;
  }
}

Kody serwera wymieniono na stronie Kody błędów. Klient dodaje własne kody:

saveResult nigdy nie nadpisuje pliku w katalogu. Wywołaj najpierw checkOutput(output, { several }), aby przed wysłaniem sprawdzić, czy do ścieżki można zapisywać.

Jakie ustawienia TypeScripta i modułów działają?#

Typy rozwiązują się przy ustawieniach moduleResolution równych nodenext, node16, bundler oraz starszym node10, łącznie ze ścieżką podrzędną @pdf123/sdk/node. Pakiet jest modułem ES, więc import działa wszędzie. require("@pdf123/sdk") z CommonJS działa w Node 22.12 lub nowszym i nie jest dostępne w Node 20.

Jak skonfigurować klienta?#

new Pdf123Client() nigdy nie czyta środowiska. clientFromEnv() z @pdf123/sdk/node czyta obie zmienne, a przekazane opcje mają pierwszeństwo. Klucz jest wysyłany w nagłówku X-API-KEY; zobacz Uwierzytelnianie.

Aby użyć własnego serwera, ustaw baseUrl na jego adres, na przykład http://localhost:8080. Zobacz Self-host.

Czy mogę używać SDK w przeglądarce?#

Tak. Główny punkt wejścia @pdf123/sdk wymaga tylko fetch i nie ma zależności od Node. Obiekty FileInput zbuduj samodzielnie z File lub Uint8Array, bo funkcje do plików znajdują się w punkcie wejścia node. Nie umieszczaj klucza API w kodzie przeglądarki, który mogą czytać inni.

Powiązane strony#

• Przegląd dla deweloperów z API REST i uwierzytelnianiem
• Wiersz poleceń pdfx, zbudowany na tym SDK
• Serwery MCP dla agentów AI
• Swagger UI i dokument OpenAPI
• Strony narzędzi: Połącz, Podziel, Kompresuj, OCR, Zabezpiecz

FAQ#

Czy SDK wymaga klucza API?#

Nie. Klient utworzony bez opcji wywołuje publiczne API anonimowo. Przekaż apiKey, aby wysyłać nagłówek X-API-KEY.

Jakiej wersji Node wymaga SDK?#

Node 20.3 lub nowszego albo Bun. Główny punkt wejścia wymaga tylko fetch, więc działa też w przeglądarkach i bundlerach.

Jak użyć narzędzia nowszego niż SDK?#

Użyj client.call. Przyjmuje identyfikator narzędzia, identyfikator operacji, taki jak general/merge-pdfs, lub ścieżkę /api/..., a także pliki i pola. Lokalnie nic nie jest walidowane ani uzupełniane wartościami domyślnymi.

Jak duży plik mogę przesłać?#

Wejścia o łącznym rozmiarze powyżej 95 MB trafiają automatycznie do API przesyłania we fragmentach. Pojedyncze bezpośrednie żądanie jest ograniczone do 100 MiB.

Dlaczego wywołanie rzuciło błąd dla PDF-a bez tabel?#

Narzędzia takie jak pdf-to-csv i pdf-to-xlsx odpowiadają bez treści, gdy PDF nie zawiera wykrywalnej tabeli. SDK rzuca wtedy Pdf123Error z kodem no_content zamiast zwracać pusty plik. Sprawdź ten kod, jeśli pusty wynik jest dla Ciebie akceptowalny.