@pdf123/sdk: TypeScript SDK ya PDF123

Ninasakinishaje SDK?#

Sakinisha kifurushi kwa kidhibiti chako cha vifurushi. Inahitajika Node 20.3 au mpya zaidi, Bun au bundler. Aina za TypeScript zimejumuishwa na @types/node haihitajiki.

npm install @pdf123/sdk

bun add @pdf123/sdk na pnpm add @pdf123/sdk hufanya kazi vilevile.

Ninaunganishaje PDF mbili?#

Unda mteja, endesha zana ya merge kwenye faili mbili kisha uhifadhi matokeo. Bila chaguo zozote, mteja huwasiliana na API ya umma bila utambulisho.

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

Matokeo yana baiti kwenye data, contentType, filename ya seva, na json kwa zana zinazorudisha ripoti. Operesheni hiyo hiyo inapatikana kama Unganisha PDF kwenye tovuti.

Niingize kutoka sehemu ipi ya kuingilia?#

Ingiza kutoka sehemu kuu ya kuingilia kwenye vivinjari na mazingira ya edge, na ongeza sehemu ya node pale tu unaposoma au kuandika faili.

Mteja ana mbinu zipi?#

Visaidizi vya katalogi ni kazi za kawaida: TOOLS inaorodhesha zana zote, getTool(id) inarudisha sehemu, thamani chaguomsingi na aina za faili zinazokubaliwa za zana moja, na toolGroup, toolSummary, matchesQuery na suggestTools husaidia kujenga vichaguzi vya zana. Mstari wa amri unachapisha katalogi ileile kwa pdfx list na pdfx describe.

Ninapitishaje chaguo kwa zana?#

params ina aina kwa kila zana. Inakubali sehemu za zana hiyo tu, na sehemu za kuchagua zinakubali thamani zinazoruhusiwa tu. Sehemu za nambari hukaguliwa dhidi ya kiwango cha chini na cha juu, na faili hukaguliwa dhidi ya aina zinazokubaliwa, kabla ya chochote kupakiwa. Thamani chaguomsingi ambazo seva inazihitaji hujazwa.

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

Mfuatano mtupu wa herufi unamaanisha "haijawekwa", kwa hiyo thamani chaguomsingi inatumika. Tazama Weka alama ya maji kwenye PDF kujua kila chaguo linafanya nini.

Ninachakataje faili nyingi?#

runBatch inaendesha zana ya faili moja, kama Bana, Zungusha au Weka nenosiri, kwenye kila ingizo kwa chaguo zilezile. Kwa chaguomsingi inaendesha faili mbili kwa wakati mmoja. Faili moja mbaya haisimamishi nyingine.

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) ni chanzo cha kuchelewesha kinachosomwa tu mfanyakazi anapokichukua, kwa hiyo faili nyingi kubwa hazikai pamoja kwenye kumbukumbu.
• onResult inapokea kila matokeo yanapokamilika. Yahifadhi hapo, na ukighairi kwenye faili ya 50 kati ya 100, ya kwanza 49 zinabaki. Kwa retainData: false safu inayorudishwa haihifadhi baiti.
• Simu yoyote inakubali timeoutMs na signal ya kuighairi.
• idempotencyKey inakuwa <key>:<index> kwa kila faili.

Zana za kichujio (vitambulisho vinavyoanza na filter-) hurudisha matched: false badala ya kutupa hitilafu hali yake isipotimia. Kwenye kundi, faili kama hiyo bado inahesabiwa kama ok.

Ninaunganishaje zana kwenye ombi moja?#

pipeline inatuma orodha ya hatua na ingizo moja au zaidi. Seva inapeleka matokeo ya kila hatua kwenye hatua inayofuata.

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

Mnyororo huu unakubali chaguo zilezile za nenosiri kama run.

Ninashughulikiaje PDF zilizosimbwa?#

Pitisha password kwa run ili kufungua kwanza ingizo lililosimbwa. Kufungua na kuendesha zana hufanyika kwenye ombi moja. Kwa zana zinazopokea faili kadhaa, kama Unganisha, pitisha passwords yenye kipengee kimoja kwa kila ingizo, ukitumia mfuatano mtupu kwa faili isiyolindwa. Kila faili hufunguliwa kivyake.

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

Kwa kundi, passwordFor(file, index) inarudisha nenosiri la kila ingizo. Ili kuondoa ulinzi moja kwa moja na kwa kudumu, tumia zana ya Ondoa nenosiri.

Hitilafu hufanyaje kazi?#

Kushindwa kunatupa Pdf123Error. Ina status (undefined pale hakukuwa na jibu), code, reason kwa chanzo cha kina kama password_required, na problem yenye maelezo ya tatizo kutoka kwa seva, yanayojumuisha hint inapokuwepo. Hitilafu za uhakiki hutupwa kabla ya chochote kupakiwa.

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

Misimbo ya seva imeorodheshwa kwenye Misimbo ya hitilafu. Mteja huongeza misimbo hii yake mwenyewe:

saveResult haibadilishi faili iliyopo ndani ya saraka. Ita checkOutput(output, { several }) kwanza ili kujua kabla ya kupakia kama njia inaweza kuandikwa.

Mipangilio ipi ya TypeScript na moduli inafanya kazi?#

Aina zinatatuliwa chini ya mipangilio ya moduleResolution ya nodenext, node16, bundler na node10 ya zamani, pamoja na njia ndogo ya @pdf123/sdk/node. Kifurushi ni moduli ya ES, kwa hiyo import inafanya kazi kila mahali. require("@pdf123/sdk") kutoka CommonJS inafanya kazi kwenye Node 22.12 au mpya zaidi na haipatikani kwenye Node 20.

Ninasanidije mteja?#

new Pdf123Client() haisomi mazingira kamwe. clientFromEnv() kutoka @pdf123/sdk/node inasoma vigeu viwili hivyo, na chaguo unazopitisha hushinda. Ufunguo hutumwa kama kichwa cha X-API-KEY; tazama Uthibitishaji.

Ili kutumia seva yako mwenyewe, weka baseUrl iwe anwani yake, kwa mfano http://localhost:8080. Tazama Self-host.

Je, naweza kutumia SDK kwenye kivinjari?#

Ndiyo. Sehemu kuu ya kuingilia @pdf123/sdk inahitaji fetch tu na haina tegemezi za Node. Jenga vitu vya FileInput mwenyewe kutoka File au Uint8Array, kwa sababu visaidizi vya faili viko kwenye sehemu ya node. Usisafirishe ufunguo wa API ndani ya msimbo wa kivinjari ambao watu wengine wanaweza kuusoma.

Kurasa zinazohusiana#

• Muhtasari wa waendelezaji wenye REST API na uthibitishaji
• Mstari wa amri wa pdfx, uliojengwa juu ya SDK hii
• Seva za MCP kwa mawakala wa AI
• Swagger UI na hati ya OpenAPI
• Kurasa za zana: Unganisha, Gawanya, Bana, OCR, Weka nenosiri

Maswali yanayoulizwa mara kwa mara#

Je, SDK inahitaji ufunguo wa API?#

Hapana. Mteja aliyeundwa bila chaguo huwasiliana na API ya umma bila utambulisho. Pitisha apiKey ili kutuma kichwa cha X-API-KEY.

SDK inahitaji toleo gani la Node?#

Node 20.3 au mpya zaidi, au Bun. Sehemu kuu ya kuingilia inahitaji fetch tu, kwa hiyo pia inaendeshwa kwenye vivinjari na bundler.

Nitapataje zana mpya kuliko SDK yangu?#

Tumia client.call. Inapokea kitambulisho cha zana, kitambulisho cha operesheni kama general/merge-pdfs au njia ya /api/..., pamoja na faili na sehemu. Hakuna kinachohakikiwa wala kujazwa kwa thamani chaguomsingi upande wa mteja.

Naweza kupakia faili yenye ukubwa gani?#

Ingizo zenye jumla ya zaidi ya MB 95 hupitia API ya upakiaji wa vipande kiotomatiki. Mwili wa ombi moja la moja kwa moja una kikomo cha MiB 100.

Kwa nini simu yangu ilitupa hitilafu kwa PDF isiyo na majedwali?#

Zana kama pdf-to-csv na pdf-to-xlsx hujibu bila maudhui PDF isipokuwa na jedwali linalotambulika. SDK inatupa Pdf123Error yenye msimbo no_content badala ya kurudisha faili tupu. Kagua msimbo huo ikiwa matokeo matupu yanakubalika kwako.