@pdf123/sdk: SDK TypeScript PDF123

Bagaimana cara memasang SDK?#

Pasang paket dengan package manager Anda. Diperlukan Node 20.3 atau lebih baru, Bun, atau bundler. Tipe TypeScript sudah disertakan dan @types/node tidak diperlukan.

npm install @pdf123/sdk

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

Bagaimana cara menggabungkan dua PDF?#

Buat klien, jalankan alat merge pada dua file, lalu simpan hasilnya. Tanpa opsi, klien berbicara dengan API publik secara anonim.

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

Hasilnya menyimpan byte di data, contentType, filename dari server, dan json untuk alat yang mengembalikan laporan. Operasi yang sama tersedia sebagai Gabungkan PDF di situs web.

Entry point mana yang harus saya impor?#

Impor dari entry root di browser dan runtime edge, dan tambahkan entry node hanya di tempat Anda membaca atau menulis file.

Metode apa saja yang dimiliki klien?#

Helper katalog berupa fungsi biasa: TOOLS mencantumkan semua alat, getTool(id) mengembalikan kolom, nilai bawaan, dan tipe file yang diterima dari satu alat, sedangkan toolGroup, toolSummary, matchesQuery, dan suggestTools membantu membuat pemilih alat. Baris perintah mencetak katalog yang sama dengan pdfx list dan pdfx describe.

Bagaimana cara meneruskan opsi ke alat?#

params bertipe per alat. Ia hanya menerima kolom milik alat itu, dan kolom pilihan hanya menerima nilai yang diizinkan. Kolom angka diperiksa terhadap nilai minimum dan maksimumnya, dan file diperiksa terhadap tipe yang diterima, sebelum apa pun diunggah. Nilai bawaan yang dibutuhkan server diisi otomatis.

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

String kosong berarti "tidak diatur", sehingga nilai bawaan berlaku. Lihat Tambah tanda air untuk fungsi setiap opsi.

Bagaimana cara memproses banyak file?#

runBatch menjalankan alat satu-file, seperti Kompres, Putar, atau Lindungi, pada setiap masukan dengan opsi yang sama. Secara bawaan dua file diproses sekaligus. Satu file yang bermasalah tidak pernah menghentikan file lainnya.

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) adalah sumber malas yang baru dibaca saat sebuah worker mengambilnya, sehingga banyak file besar tidak pernah berada di memori bersamaan.
• onResult menerima setiap hasil begitu selesai. Simpan hasilnya di sana, dan pembatalan pada file ke-50 dari 100 tetap menyimpan 49 file pertama. Dengan retainData: false, array yang dikembalikan tidak menyimpan byte-nya.
• Setiap panggilan menerima timeoutMs dan signal untuk membatalkannya.
• idempotencyKey menjadi <key>:<index> untuk setiap file.

Alat filter (id yang diawali filter-) menghasilkan matched: false alih-alih melempar galat saat kondisinya tidak terpenuhi. Dalam batch, file seperti itu tetap dihitung sebagai ok.

Bagaimana cara merangkai alat dalam satu permintaan?#

pipeline mengirim daftar langkah dan satu atau beberapa masukan. Server meneruskan keluaran tiap langkah ke langkah berikutnya.

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

Pipeline menerima opsi kata sandi yang sama seperti run.

Bagaimana cara menangani PDF terenkripsi?#

Berikan password ke run untuk membuka masukan terenkripsi lebih dulu. Pembukaan dan alat dijalankan dalam satu permintaan. Untuk alat yang menerima beberapa file, seperti Gabungkan, berikan passwords dengan satu entri per masukan, memakai string kosong untuk file yang terbuka. Setiap file dibuka secara terpisah.

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 batch, passwordFor(file, index) mengembalikan kata sandi untuk tiap masukan. Untuk menghapus perlindungan secara permanen, gunakan alat Buka kunci.

Bagaimana galat ditangani?#

Kegagalan melempar Pdf123Error. Objek ini memiliki status (undefined jika tidak ada respons), code, reason untuk penyebab yang lebih rinci seperti password_required, dan problem berisi rincian masalah dari server, termasuk hint jika ada. Galat validasi dilempar sebelum apa pun diunggah.

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

Kode dari server tercantum di Kode galat. Klien menambahkan kode berikut miliknya sendiri:

saveResult tidak pernah menimpa file di dalam direktori. Panggil checkOutput(output, { several }) lebih dulu untuk mengetahui, sebelum mengunggah, apakah sebuah jalur dapat ditulis.

Pengaturan TypeScript dan modul mana yang berfungsi?#

Tipe ini dapat di-resolve dengan pengaturan moduleResolution nodenext, node16, bundler, dan node10 yang lebih lama, termasuk subpath @pdf123/sdk/node. Paket ini adalah modul ES, sehingga import berfungsi di mana saja. require("@pdf123/sdk") dari CommonJS berfungsi di Node 22.12 atau lebih baru dan tidak tersedia di Node 20.

Bagaimana cara mengonfigurasi klien?#

new Pdf123Client() tidak pernah membaca lingkungan. clientFromEnv() dari @pdf123/sdk/node membaca kedua variabel itu, dan opsi yang Anda berikan lebih diutamakan. Kunci dikirim sebagai header X-API-KEY; lihat Autentikasi.

Untuk memakai server Anda sendiri, setel baseUrl ke alamatnya, misalnya http://localhost:8080. Lihat Self-host.

Bisakah saya memakai SDK di browser?#

Bisa. Entry root @pdf123/sdk hanya membutuhkan fetch dan tidak memiliki dependensi Node. Buat objek FileInput sendiri dari File atau Uint8Array, karena helper file berada di entry node. Jangan menyertakan kunci API dalam kode browser yang dapat dibaca orang lain.

Halaman terkait#

• Ikhtisar pengembang dengan REST API dan autentikasi
• Baris perintah pdfx, yang dibangun di atas SDK ini
• Server MCP untuk agen AI
• Swagger UI dan dokumen OpenAPI
• Halaman alat: Gabungkan, Pisahkan, Kompres, OCR, Lindungi

FAQ#

Apakah SDK memerlukan kunci API?#

Tidak. Klien yang dibuat tanpa opsi memanggil API publik secara anonim. Berikan apiKey untuk mengirim header X-API-KEY.

Versi Node berapa yang dibutuhkan SDK?#

Node 20.3 atau lebih baru, atau Bun. Entry root hanya membutuhkan fetch, sehingga juga berjalan di browser dan bundler.

Bagaimana cara mendapatkan alat yang lebih baru daripada SDK?#

Gunakan client.call. Metode ini menerima id alat, id operasi seperti general/merge-pdfs, atau jalur /api/..., beserta file dan kolom. Tidak ada yang divalidasi atau diisi nilai bawaannya secara lokal.

Berapa ukuran file yang dapat saya unggah?#

Masukan yang totalnya di atas 95 MB otomatis melalui API unggah bertahap. Satu isi permintaan langsung dibatasi hingga 100 MiB.

Mengapa panggilan saya melempar galat untuk PDF tanpa tabel?#

Alat seperti pdf-to-csv dan pdf-to-xlsx menjawab tanpa konten jika PDF tidak memiliki tabel yang dapat dideteksi. SDK melempar Pdf123Error dengan kode no_content alih-alih mengembalikan file kosong. Periksa kode itu jika hasil kosong dapat diterima.