@pdf123/sdk: TypeScript SDK на PDF123

Как да инсталирам SDK?#

Инсталирайте пакета с вашия мениджър на пакети. Необходими са Node 20.3 или по-нов, Bun или bundler. TypeScript типовете са включени и @types/node не е нужен.

npm install @pdf123/sdk

bun add @pdf123/sdk и pnpm add @pdf123/sdk работят по същия начин.

Как да обединя два PDF файла?#

Създайте клиент, изпълнете инструмента merge върху два файла и запазете резултата. Без опции клиентът се обръща към публичния API анонимно.

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);

Резултатът съдържа байтовете в data, contentType, името на файла от сървъра в filename и json за инструментите, които връщат отчет. Същата операция е достъпна в сайта като Обединяване на PDF.

Кой входен модул да импортирам?#

В браузъри и edge среди импортирайте от основния модул и добавяйте модула node само там, където четете или записвате файлове.

Какви методи има клиентът?#

Помощните функции за каталога са обикновени функции: TOOLS изброява всички инструменти, getTool(id) връща полетата, стойностите по подразбиране и приетите типове файлове на един инструмент, а toolGroup, toolSummary, matchesQuery и suggestTools помагат за изграждане на избор на инструменти. Командният ред показва същия каталог с pdfx list и pdfx describe.

Как да задам опции на инструмент?#

params е типизиран за всеки инструмент. Приема само полетата на този инструмент, а полетата с избор приемат само допустимите си стойности. Числовите полета се проверяват спрямо минимума и максимума си, а файлът се проверява спрямо приетите типове, всичко това преди да се качи каквото и да е. Стойностите по подразбиране, от които сървърът се нуждае, се попълват.

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

Празен низ означава "не е зададено", затова се прилага стойността по подразбиране. Вижте Воден знак на PDF, за да разберете какво прави всяка опция.

Как да обработя много файлове?#

runBatch изпълнява инструмент за един файл, като Компресиране, Завъртане или Защита, върху всеки вход със същите опции. По подразбиране обработва по два файла едновременно. Един лош файл никога не спира останалите.

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) е мързелив източник, който се чете едва когато работник го вземе, така че много големи файлове никога не заемат паметта едновременно.
• onResult получава всеки резултат веднага щом е готов. Запазвайте го там и при отказ на файл 50 от 100 първите 49 остават. С retainData: false върнатият масив не пази байтовете.
• Всяко извикване приема timeoutMs и signal, за да бъде отказано.
• idempotencyKey става <key>:<index> за всеки файл.

Филтриращите инструменти (идентификатори, започващи с filter-) връщат matched: false, вместо да хвърлят грешка, когато условието им не е изпълнено. В пакетна обработка такъв файл все пак се брои за ok.

Как да свържа инструменти в една заявка?#

pipeline изпраща списък със стъпки и един или повече входа. Сървърът подава резултата от всяка стъпка на следващата.

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" });

Последователностите приемат същите опции за пароли като run.

Как да работя с криптирани PDF файлове?#

Подайте password на run, за да се отвори първо криптираният вход. Отключването и инструментът се изпълняват в една заявка. За инструменти с няколко файла, като Обединяване, подайте passwords с по един запис за всеки вход, като за отворен файл използвате празен низ. Всеки файл се отключва поотделно.

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", ""],
});

При пакетна обработка passwordFor(file, index) връща паролата за всеки вход. За да премахнете защитата завинаги, използвайте инструмента Отключване.

Как работят грешките?#

Неуспешните заявки хвърлят Pdf123Error. Той има status (undefined, когато няма отговор), code, reason за точната причина, например password_required, и problem с описанието на проблема от сървъра, което включва hint, когато има такъв. Грешките при валидиране се хвърлят, преди да е качено каквото и да е.

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;
  }
}

Кодовете на сървъра са изброени в Кодове за грешки. Клиентът добавя и тези свои кодове:

saveResult никога не презаписва файл в директория. Извикайте първо checkOutput(output, { several }), за да разберете преди качването дали в пътя може да се пише.

Кои настройки на TypeScript и модулите работят?#

Типовете се разрешават при настройките на moduleResolution nodenext, node16, bundler и по-старата node10, включително поддиректорията @pdf123/sdk/node. Пакетът е ES модул, така че import работи навсякъде. require("@pdf123/sdk") от CommonJS работи на Node 22.12 или по-нов и не е наличен на Node 20.

Как да настроя клиента?#

new Pdf123Client() никога не чете средата. clientFromEnv() от @pdf123/sdk/node чете двете променливи, а опциите, които подадете, имат предимство. Ключът се изпраща в заглавката X-API-KEY; вижте Удостоверяване.

За да използвате собствен сървър, задайте baseUrl към неговия адрес, например http://localhost:8080. Вижте Self-host.

Мога ли да използвам SDK в браузър?#

Да. Основният модул @pdf123/sdk изисква само fetch и няма зависимости от Node. Създавайте обектите FileInput сами от File или Uint8Array, защото помощните функции за файлове са в модула node. Не включвайте API ключ в код за браузър, който други хора могат да прочетат.

Свързани страници#

• Преглед за разработчици с REST API и удостоверяването
• Командният ред pdfx, изграден върху този SDK
• MCP сървъри за AI агенти
• Swagger UI и документът OpenAPI
• Страници на инструменти: Обединяване, Разделяне, Компресиране, OCR, Защита

Често задавани въпроси#

Нужен ли е API ключ на SDK?#

Не. Клиент, създаден без опции, извиква публичния API анонимно. Подайте apiKey, за да се изпрати заглавката X-API-KEY.

Коя версия на Node изисква SDK?#

Node 20.3 или по-нова, или Bun. Основният модул изисква само fetch, затова работи и в браузъри и bundler-и.

Как да използвам инструмент, който е по-нов от SDK?#

Използвайте client.call. Тя приема идентификатор на инструмент, идентификатор на операция като general/merge-pdfs или път /api/..., плюс файлове и полета. Локално нищо не се валидира и не се попълват стойности по подразбиране.

Какъв е максималният размер на качвания файл?#

Входове с общ размер над 95 MB минават автоматично през API за качване на части. Тялото на една директна заявка е ограничено до 100 MiB.

Защо извикването ми хвърли грешка за PDF без таблици?#

Инструменти като pdf-to-csv и pdf-to-xlsx отговарят без съдържание, когато PDF файлът няма откриваема таблица. SDK хвърля Pdf123Error с код no_content, вместо да върне празен файл. Проверете този код, ако празният резултат е приемлив за вас.