@pdf123/sdk: SDK TypeScript PDF123

Bagaimana saya memasang SDK?#

Pasang pakej dengan pengurus pakej anda. Node 20.3 atau lebih baharu, Bun atau pembundel diperlukan. Jenis TypeScript disertakan dan @types/node tidak diperlukan.

npm install @pdf123/sdk

bun add @pdf123/sdk dan pnpm add @pdf123/sdk berfungsi dengan cara yang sama.

Bagaimana saya menggabungkan dua PDF?#

Cipta klien, jalankan alat merge pada dua fail dan simpan hasilnya. Tanpa sebarang pilihan, klien berhubung dengan API awam tanpa nama.

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

Hasil itu mengandungi bait dalam data, contentType, filename daripada pelayan, dan json untuk alat yang memulangkan laporan. Operasi yang sama tersedia sebagai Gabungkan PDF di laman web.

Titik masuk manakah yang patut saya import?#

Import daripada titik masuk akar dalam pelayar dan runtime edge, dan tambah titik masuk node hanya di tempat anda membaca atau menulis fail.

Apakah kaedah yang ada pada klien?#

Fungsi bantu katalog ialah fungsi biasa: TOOLS menyenaraikan semua alat, getTool(id) memulangkan medan, nilai lalai dan jenis fail yang diterima bagi satu alat, dan toolGroup, toolSummary, matchesQuery serta suggestTools membantu membina pemilih alat. Baris perintah mencetak katalog yang sama dengan pdfx list dan pdfx describe.

Bagaimana saya menghantar pilihan kepada alat?#

params ditaip bagi setiap alat. Ia hanya menerima medan alat itu, dan medan pilihan hanya menerima nilai yang dibenarkan. Medan nombor disemak mengikut minimum dan maksimumnya, dan fail disemak mengikut jenis yang diterima, sebelum apa-apa dimuat naik. Nilai lalai yang diperlukan oleh pelayan diisi.

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

Rentetan kosong bermaksud "tidak ditetapkan", jadi nilai lalai digunakan. Lihat Tambah tanda air pada PDF untuk fungsi setiap pilihan.

Bagaimana saya memproses banyak fail?#

runBatch menjalankan alat satu fail, seperti Mampatkan, Putar atau Lindungi, pada setiap input dengan pilihan yang sama. Secara lalai ia memproses dua fail pada satu masa. Satu fail yang bermasalah tidak pernah menghentikan yang lain.

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) ialah sumber malas yang hanya dibaca apabila pekerja mengambilnya, jadi banyak fail besar tidak pernah berada dalam memori serentak.
• onResult menerima setiap hasil sebaik sahaja siap. Simpan di situ, dan pembatalan pada fail ke-50 daripada 100 mengekalkan 49 yang pertama. Dengan retainData: false, tatasusunan yang dipulangkan tidak menyimpan bait.
• Mana-mana panggilan menerima timeoutMs dan signal untuk membatalkannya.
• idempotencyKey menjadi <key>:<index> bagi setiap fail.

Alat penapis (id bermula dengan filter-) menghasilkan matched: false dan bukannya membuang ralat apabila syaratnya tidak dipenuhi. Dalam kelompok, fail sedemikian masih dikira ok.

Bagaimana saya merangkaikan alat dalam satu permintaan?#

pipeline menghantar senarai langkah dan satu atau lebih input. Pelayan menyalurkan output setiap langkah kepada langkah seterusnya.

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

Saluran paip menerima pilihan kata laluan yang sama seperti run.

Bagaimana saya bekerja dengan PDF yang disulitkan?#

Hantar password kepada run untuk membuka input yang disulitkan terlebih dahulu. Pembukaan kunci dan alat dijalankan dalam satu permintaan. Untuk alat yang menerima beberapa fail, seperti Gabungkan, hantar passwords dengan satu entri bagi setiap input, dan gunakan rentetan kosong untuk fail yang terbuka. Setiap fail dibuka kuncinya secara berasingan.

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

Untuk kelompok, passwordFor(file, index) memulangkan kata laluan bagi setiap input. Untuk membuang perlindungan secara kekal, gunakan alat Buka kunci.

Bagaimana ralat berfungsi?#

Kegagalan membuang Pdf123Error. Ia mempunyai status (undefined apabila tiada respons), code, reason untuk punca terperinci seperti password_required, dan problem dengan butiran masalah daripada pelayan, termasuk hint jika ada. Ralat pengesahan dibuang sebelum apa-apa dimuat naik.

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

Kod pelayan disenaraikan di Kod ralat. Klien menambah kod tersendiri ini:

saveResult tidak pernah menimpa fail di dalam direktori. Panggil checkOutput(output, { several }) dahulu untuk mengetahui sebelum memuat naik sama ada sesuatu laluan boleh ditulis.

Tetapan TypeScript dan modul manakah yang berfungsi?#

Jenis diselesaikan di bawah tetapan moduleResolution iaitu nodenext, node16, bundler dan node10 yang lebih lama, termasuk subhala @pdf123/sdk/node. Pakej ini ialah modul ES, jadi import berfungsi di mana-mana. require("@pdf123/sdk") daripada CommonJS berfungsi pada Node 22.12 atau lebih baharu dan tidak tersedia pada Node 20.

Bagaimana saya mengkonfigurasi klien?#

new Pdf123Client() tidak pernah membaca persekitaran. clientFromEnv() daripada @pdf123/sdk/node membaca dua pemboleh ubah itu, dan pilihan yang anda berikan diutamakan. Kunci dihantar sebagai pengepala X-API-KEY; lihat Pengesahan.

Untuk menggunakan pelayan anda sendiri, tetapkan baseUrl kepada alamatnya, contohnya http://localhost:8080. Lihat Self-host.

Bolehkah saya menggunakan SDK dalam pelayar?#

Ya. Titik masuk akar @pdf123/sdk hanya memerlukan fetch dan tidak mempunyai kebergantungan Node. Bina objek FileInput sendiri daripada File atau Uint8Array, kerana fungsi bantu fail terdapat dalam titik masuk node. Jangan sertakan kunci API dalam kod pelayar yang boleh dibaca orang lain.

Halaman berkaitan#

• Gambaran keseluruhan pembangun dengan REST API dan pengesahan
• Baris perintah pdfx, dibina di atas SDK ini
• Pelayan MCP untuk ejen AI
• Swagger UI dan dokumen OpenAPI
• Halaman alat: Gabungkan, Asingkan, Mampatkan, OCR, Lindungi

FAQ#

Adakah SDK memerlukan kunci API?#

Tidak. Klien yang dicipta tanpa pilihan memanggil API awam tanpa nama. Hantar apiKey untuk menghantar pengepala X-API-KEY.

Versi Node manakah yang diperlukan oleh SDK?#

Node 20.3 atau lebih baharu, atau Bun. Titik masuk akar hanya memerlukan fetch, jadi ia turut berjalan dalam pelayar dan pembundel.

Bagaimana saya mendapat alat yang lebih baharu daripada SDK?#

Gunakan client.call. Ia menerima id alat, id operasi seperti general/merge-pdfs atau laluan /api/..., serta fail dan medan. Tiada pengesahan atau nilai lalai dilakukan secara setempat.

Seberapa besar fail yang boleh saya muat naik?#

Input yang jumlahnya melebihi 95 MB melalui API muat naik berketul secara automatik. Satu badan permintaan langsung dihadkan kepada 100 MiB.

Mengapa panggilan saya membuang ralat untuk PDF tanpa jadual?#

Alat seperti pdf-to-csv dan pdf-to-xlsx menjawab tanpa kandungan apabila PDF tiada jadual yang dapat dikesan. SDK membuang Pdf123Error dengan kod no_content dan bukannya memulangkan fail kosong. Semak kod itu jika hasil kosong boleh diterima.