@pdf123/sdk: PDF टूल के लिए TypeScript SDK

SDK कैसे इंस्टॉल करें?

पैकेज को अपने पैकेज मैनेजर से इंस्टॉल करें। Node 20.3 या नया संस्करण, Bun या कोई बंडलर चाहिए। TypeScript टाइप साथ में आते हैं और @types/node की ज़रूरत नहीं है।

इंस्टॉलbash

npm install @pdf123/sdk

bun add @pdf123/sdk और pnpm add @pdf123/sdk भी इसी तरह काम करते हैं।

दो PDF कैसे मिलाएँ?

एक क्लाइंट बनाएँ, दो फ़ाइलों पर merge टूल चलाएँ और नतीजा सेव करें। बिना किसी विकल्प के क्लाइंट सार्वजनिक API से गुमनाम रूप से बात करता है।

मिलाएँ और सेव करेंts

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 मिलाएँ के नाम से उपलब्ध है।

कौन-सा एंट्री पॉइंट इम्पोर्ट करें?

एंट्री पॉइंट	ज़रूरत	क्या देता है
`@pdf123/sdk`	सिर्फ़ `fetch`	`Pdf123Client`, `TOOLS`, `getTool`, `Pdf123Error` और कैटलॉग हेल्पर
`@pdf123/sdk/node`	Node या Bun	`readFileInput`, `fileSource`, `saveResult`, `checkOutput` और `clientFromEnv`

ब्राउज़र और एज रनटाइम में रूट एंट्री से इम्पोर्ट करें, और node एंट्री केवल वहीं जोड़ें जहाँ आप फ़ाइलें पढ़ते या लिखते हैं।

क्लाइंट में कौन-से मेथड हैं?

मेथड	क्या करता है
`run(tool, { input, params })`	एक टूल चलाता है और नतीजा लौटाता है
`runBatch(tool, inputs, options)`	एक-फ़ाइल वाले टूल को कई इनपुट पर चलाता है और हर इनपुट के लिए एक प्रविष्टि लौटाता है
`pipeline(steps, input, options)`	एक अनुरोध में कई टूल चलाता है
`call(target, files, fields)`	टूल आईडी, ऑपरेशन आईडी या `/api/...` पथ पर कच्चा अनुरोध भेजता है
`upload(file)`	चंक अपलोड API से एक फ़ाइल अपलोड करता है और उसकी आईडी लौटाता है

कैटलॉग हेल्पर सादे फ़ंक्शन हैं: TOOLS सभी टूल की सूची है, getTool(id) एक टूल के फ़ील्ड, डिफ़ॉल्ट और स्वीकार्य फ़ाइल प्रकार लौटाता है, और toolGroup, toolSummary, matchesQuery व suggestTools टूल चुनने वाले इंटरफ़ेस बनाने में मदद करते हैं। कमांड लाइन यही कैटलॉग pdfx list और pdfx describe से दिखाती है।

टूल को विकल्प कैसे दें?

params हर टूल के हिसाब से टाइप किया होता है। यह केवल उसी टूल की फ़ील्ड स्वीकार करता है, और विकल्प वाली फ़ील्ड केवल अनुमत मान लेती हैं। संख्या वाली फ़ील्ड की जाँच उनके न्यूनतम और अधिकतम से होती है, और फ़ाइल की जाँच स्वीकार्य प्रकारों से, यह सब कुछ अपलोड होने से पहले होता है। सर्वर को जिन डिफ़ॉल्ट मानों की ज़रूरत होती है, वे भर दिए जाते हैं।

विकल्पों के साथ वॉटरमार्कts

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

खाली स्ट्रिंग का मतलब "सेट नहीं है" होता है, इसलिए डिफ़ॉल्ट लागू होता है। हर विकल्प क्या करता है, यह वॉटरमार्क लगाएँ पर देखें।

कई फ़ाइलें कैसे प्रोसेस करें?

runBatch एक-फ़ाइल वाले टूल, जैसे संपीड़ित करें, घुमाएँ या सुरक्षित करें, को हर इनपुट पर समान विकल्पों के साथ चलाता है। डिफ़ॉल्ट रूप से यह एक बार में दो फ़ाइलें चलाता है। एक खराब फ़ाइल बाकी को कभी नहीं रोकती।

रद्द करने की सुविधा वाला बैचts

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 को हर नतीजा पूरा होते ही मिलता है। उसे वहीं सेव करें; तब 100 में से 50वीं फ़ाइल पर रद्द करने पर पहली 49 बची रहती हैं। retainData: false के साथ लौटाई गई ऐरे बाइट नहीं रखती।
हर कॉल timeoutMs और उसे रद्द करने के लिए signal स्वीकार करता है।
हर फ़ाइल के लिए idempotencyKey बदलकर <key>:<index> हो जाती है।

फ़िल्टर टूल (जिनकी आईडी filter- से शुरू होती है) शर्त पूरी न होने पर त्रुटि फेंकने के बजाय matched: false के साथ पूरे होते हैं। बैच में ऐसी फ़ाइल भी ok गिनी जाती है।

एक अनुरोध में टूल कैसे जोड़ें?

pipeline चरणों की सूची और एक या अधिक इनपुट भेजता है। सर्वर हर चरण का आउटपुट अगले चरण को दे देता है।

मिलाएँ, वॉटरमार्क लगाएँ, संपीड़ित करेंts

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 के साथ कैसे काम करें?

एन्क्रिप्टेड इनपुट पहले खोलने के लिए run को password दें। अनलॉक और टूल एक ही अनुरोध में चलते हैं। कई फ़ाइलें लेने वाले टूल, जैसे मिलाएँ, के लिए passwords दें, जिसमें हर इनपुट के लिए एक प्रविष्टि हो और खुली फ़ाइल के लिए खाली स्ट्रिंग। हर फ़ाइल अलग से अनलॉक होती है।

पासवर्डts

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, password_required जैसे बारीक कारण के लिए reason, और सर्वर के समस्या-विवरण के साथ problem होता है, जिसमें hint भी होता है यदि कोई हो। वैलिडेशन त्रुटियाँ कुछ भी अपलोड होने से पहले फेंकी जाती हैं।

त्रुटि सँभालेंts

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

सर्वर के कोड त्रुटि कोड पर सूचीबद्ध हैं। क्लाइंट अपने ये कोड जोड़ता है:

कोड	मतलब
`network_error`	अनुरोध का कोई जवाब नहीं मिला
`timeout`	अनुरोध `timeoutMs` से ज़्यादा चला
`cancelled`	आपके `signal` ने कॉल रद्द कर दिया
`input_unreadable`	स्थानीय पथ पढ़ा नहीं जा सका
`output_unwritable`	नतीजा दिए गए पथ पर सेव नहीं हो सका
`output_mismatch`	`saveResult` ने ZIP को `.pdf` नाम से लिखने से मना कर दिया
`unsupported_file_type`	टूल यह फ़ाइल प्रकार स्वीकार नहीं करता
`unknown_tool`	टूल आईडी मौजूद नहीं है; संदेश में मिलती-जुलती आईडी सुझाई जाती हैं
`invalid_target`	`call` ने `..`, `.` या खाली खंड वाले `/api/...` पथ को अस्वीकार कर दिया
`no_content`	टूल के पास लौटाने को कुछ नहीं था (HTTP 204)

saveResult किसी डायरेक्टरी के भीतर की फ़ाइल को कभी अधिलेखित नहीं करता। अपलोड से पहले यह जानने के लिए कि कोई पथ लिखा जा सकता है या नहीं, पहले checkOutput(output, { several }) कॉल करें।

कौन-सी TypeScript और मॉड्यूल सेटिंग चलती हैं?

टाइप moduleResolution की सेटिंग nodenext, node16, bundler और पुरानी node10 में सुलझते हैं, @pdf123/sdk/node सबपाथ समेत। पैकेज ES मॉड्यूल है, इसलिए import हर जगह चलता है। CommonJS से require("@pdf123/sdk") Node 22.12 या नए संस्करण पर चलता है और Node 20 पर उपलब्ध नहीं है।

क्लाइंट को कैसे कॉन्फ़िगर करें?

विकल्प	एनवायरनमेंट वेरिएबल	डिफ़ॉल्ट
`baseUrl`	`PDFX_API_BASE`	`https://pdf123.xyz`
`apiKey`	`PDFX_API_KEY`	कोई नहीं, गुमनाम
`timeoutMs`	कोई नहीं	300000

new Pdf123Client() एनवायरनमेंट कभी नहीं पढ़ता। @pdf123/sdk/node का clientFromEnv() दोनों वेरिएबल पढ़ता है, और आपके दिए विकल्प प्राथमिकता पाते हैं। कुंजी X-API-KEY हेडर में भेजी जाती है; देखें प्रमाणीकरण।

अपना सर्वर इस्तेमाल करने के लिए baseUrl को उसके पते पर सेट करें, जैसे http://localhost:8080। देखें सेल्फ-होस्ट।

क्या SDK ब्राउज़र में इस्तेमाल हो सकता है?

हाँ। रूट एंट्री @pdf123/sdk को केवल fetch चाहिए और उसमें Node की कोई निर्भरता नहीं है। FileInput ऑब्जेक्ट File या Uint8Array से खुद बनाएँ, क्योंकि फ़ाइल हेल्पर node एंट्री में हैं। ब्राउज़र कोड में API कुंजी न डालें, क्योंकि उसे दूसरे लोग पढ़ सकते हैं।

डेवलपर अवलोकन, जिसमें REST API और प्रमाणीकरण है
pdfx कमांड लाइन, जो इसी SDK पर बनी है
AI एजेंट के लिए MCP सर्वर
Swagger UI और OpenAPI दस्तावेज़
टूल पेज: मिलाएँ, बाँटें, संपीड़ित करें, OCR, सुरक्षित करें

FAQ

क्या SDK को API कुंजी चाहिए?

नहीं। बिना विकल्प के बना क्लाइंट सार्वजनिक API को गुमनाम रूप से कॉल करता है। X-API-KEY हेडर भेजने के लिए apiKey दें।

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 खाली फ़ाइल लौटाने के बजाय no_content कोड के साथ Pdf123Error फेंकता है। यदि खाली नतीजा आपके लिए स्वीकार्य है, तो इसी कोड की जाँच करें।

SDK कैसे इंस्टॉल करें?#

दो PDF कैसे मिलाएँ?#

कौन-सा एंट्री पॉइंट इम्पोर्ट करें?#

क्लाइंट में कौन-से मेथड हैं?#

टूल को विकल्प कैसे दें?#

कई फ़ाइलें कैसे प्रोसेस करें?#

एक अनुरोध में टूल कैसे जोड़ें?#

एन्क्रिप्टेड PDF के साथ कैसे काम करें?#

त्रुटियाँ कैसे काम करती हैं?#

कौन-सी TypeScript और मॉड्यूल सेटिंग चलती हैं?#

क्लाइंट को कैसे कॉन्फ़िगर करें?#

क्या SDK ब्राउज़र में इस्तेमाल हो सकता है?#

संबंधित पेज#

FAQ#

क्या SDK को API कुंजी चाहिए?#

SDK को Node का कौन-सा संस्करण चाहिए?#

SDK से नया टूल कैसे इस्तेमाल करें?#

कितनी बड़ी फ़ाइल अपलोड कर सकते हैं?#

बिना तालिका वाले PDF पर मेरा कॉल त्रुटि क्यों फेंक गया?#