@pdf123/sdk: TypeScript SDK ของ PDF123

จะติดตั้ง SDK ได้อย่างไร#

ติดตั้งแพ็กเกจด้วยตัวจัดการแพ็กเกจของคุณ ต้องใช้ Node 20.3 ขึ้นไป Bun หรือบันเดลเลอร์ มีชนิดข้อมูล 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) เป็นแหล่งข้อมูลแบบ lazy ที่อ่านเมื่อมี worker หยิบไปเท่านั้น ไฟล์ขนาดใหญ่จำนวนมากจึงไม่อยู่ในหน่วยความจำพร้อมกัน
• 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 รุ่นเก่า รวมถึง subpath @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 ดูโฮสต์เอง

ใช้ SDK ในเบราว์เซอร์ได้หรือไม่#

ได้ จุดเข้าใช้งานหลัก @pdf123/sdk ต้องการเพียง fetch และไม่พึ่งพา Node คุณต้องสร้างออบเจ็กต์ FileInput จาก File หรือ Uint8Array เอง เพราะตัวช่วยด้านไฟล์อยู่ในจุดเข้าใช้งาน node อย่าใส่คีย์ API ไว้ในโค้ดเบราว์เซอร์ที่คนอื่นอ่านได้

หน้าที่เกี่ยวข้อง#

• ภาพรวมสำหรับนักพัฒนา ซึ่งมี REST API และการยืนยันตัวตน
• บรรทัดคำสั่ง pdfx ที่สร้างบน SDK นี้
• เซิร์ฟเวอร์ MCP สำหรับเอเจนต์ AI
• Swagger UI และเอกสาร OpenAPI
• หน้าเครื่องมือ: รวม, แยก, บีบอัด, OCR, ใส่รหัสผ่าน

คำถามที่พบบ่อย#

SDK ต้องใช้คีย์ API หรือไม่#

ไม่ต้อง ไคลเอนต์ที่สร้างโดยไม่มีตัวเลือกจะเรียก API สาธารณะแบบไม่ระบุตัวตน ส่ง apiKey เพื่อส่งเฮดเดอร์ X-API-KEY

SDK ต้องใช้ Node เวอร์ชันใด#

Node 20.3 ขึ้นไป หรือ Bun จุดเข้าใช้งานหลักต้องการเพียง fetch จึงรันในเบราว์เซอร์และบันเดลเลอร์ได้ด้วย

จะใช้เครื่องมือที่ใหม่กว่า SDK ได้อย่างไร#

ใช้ client.call โดยรับรหัสเครื่องมือ รหัสการทำงาน เช่น general/merge-pdfs หรือเส้นทาง /api/... พร้อมไฟล์และฟิลด์ ไม่มีการตรวจสอบหรือเติมค่าเริ่มต้นฝั่งไคลเอนต์

อัปโหลดไฟล์ใหญ่ได้เท่าไร#

อินพุตที่มีขนาดรวมเกิน 95 MB จะผ่าน API อัปโหลดแบบแบ่งส่วนโดยอัตโนมัติ เนื้อหาของคำขอโดยตรงหนึ่งครั้งจำกัดที่ 100 MiB

ทำไมการเรียกจึงโยนข้อผิดพลาดกับ PDF ที่ไม่มีตาราง#

เครื่องมืออย่าง pdf-to-csv และ pdf-to-xlsx ตอบกลับโดยไม่มีเนื้อหาเมื่อ PDF ไม่มีตารางที่ตรวจพบ SDK จึงโยน Pdf123Error ด้วยรหัส no_content แทนการคืนไฟล์ว่าง ให้ตรวจรหัสนี้หากยอมรับผลลัพธ์ว่างได้