{"id":27781313,"url":"https://github.com/thoven87/gotenberg-kit","last_synced_at":"2025-05-13T12:53:47.004Z","repository":{"id":289395172,"uuid":"971089038","full_name":"thoven87/gotenberg-kit","owner":"thoven87","description":"A Swift library that interacts with Gotenberg's different modules to convert a variety of document formats to PDF files.","archived":false,"fork":false,"pushed_at":"2025-05-09T20:53:58.000Z","size":256,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-09T21:39:00.536Z","etag":null,"topics":["api-client","api-client-swift","chromium","convert-to-pdf","docx-to-pdf","dotx","gotenberg","html","html-to-pdf","libreoffice","markdown","pdf","pdf-converter","pptx","screenshots","server-side-swift","swift","wkhtmltopdf","xslx"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thoven87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-23T02:09:05.000Z","updated_at":"2025-05-09T20:54:01.000Z","dependencies_parsed_at":"2025-05-09T21:38:36.985Z","dependency_job_id":"abdf5433-897c-4b7b-beb3-7a2b7a20d343","html_url":"https://github.com/thoven87/gotenberg-kit","commit_stats":null,"previous_names":["thoven87/gotenberg-kit"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoven87%2Fgotenberg-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoven87%2Fgotenberg-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoven87%2Fgotenberg-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoven87%2Fgotenberg-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thoven87","download_url":"https://codeload.github.com/thoven87/gotenberg-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948208,"owners_count":21988952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-client-swift","chromium","convert-to-pdf","docx-to-pdf","dotx","gotenberg","html","html-to-pdf","libreoffice","markdown","pdf","pdf-converter","pptx","screenshots","server-side-swift","swift","wkhtmltopdf","xslx"],"created_at":"2025-04-30T13:00:47.290Z","updated_at":"2025-05-13T12:53:46.983Z","avatar_url":"https://github.com/thoven87.png","language":"Swift","funding_links":[],"categories":["Clients"],"sub_categories":[],"readme":"# GotenbergKit\n\n[![](https://img.shields.io/github/v/release/thoven87/gotenberg-kit?include_prereleases)](https://github.com/thoven87/gotenberg-kit/releases)\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fthoven87%2Fgotenberg-kit%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/thoven87/gotenberg-kit)\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fthoven87%2Fgotenberg-kit%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/thoven87/gotenberg-kit)\n[![CI](https://github.com/thoven87/gotenberg-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/thoven87/gotenberg-kit/actions/workflows/ci.yml)\n\nA Swift library that interacts with [Gotenberg](https://gotenberg.dev/)'s different modules to convert a variety of document formats to PDF files.\n\n# Table of Contents\n\n1. [Getting Started](#getting-started)\n   - [Installation](#snippets)\n   - [Prerequisites](#prerequisites)\n   - [Configuration](#configuration)\n2. [Authentication](#authentication)\n   - [Basic Authentication](#basic-authentication)\n   - [Advanced Authentication](#advanced-authentication)\n3. [Core Features](#core-features)\n   - [Chromium](#chromium)\n     - [URL](#url)\n     - [HTML](#html)\n     - [Markdown](#markdown)\n     - [Screenshot](#screenshot)\n   - [LibreOffice](#libreoffice)\n   - [PDF Engines](#pdf-engines)\n     - [Format Conversion](#format-conversion)\n     - [Merging](#merging)\n     - [Metadata Management](#metadata-management)\n     - [File Generation](#file-generation)\n   - [PDF Splitting](#pdf-splitting)\n4. [Usage Example](#snippet)\n\n## Getting Started\n\n## Snippets\nTo incorporate `gotenberg-kit` into your project, follow the snippets below for SPM dependencies.\n\n### SPM\n```swift\n.package(url: \"https://github.com/thoven87/gotenberg-kit.git\", from: \"0.1.0\")\n\n.target(name: \"MyApp\", dependencies: [.product(name: \"GotenbergKit\", package: \"gotenberg-kit\")]),\n```\n\n## Prerequisites\n\nBefore attempting to use `GotenbergKit`, be sure you install [Docker](https://www.docker.com/) if you have not already done so.\n\nOnce the docker Daemon is up and running, you can start a default Docker container of [Gotenberg](https://gotenberg.dev/) as follows:\n\n```bash\ndocker run --rm -p 7100:7100 gotenberg/gotenberg:8 gotenberg --api-port=7100\n```\n\n## Configuration\n\nCreate an instance of `Gotenberg` class and pass your `Gotenberg` `endpoint` url as a constructor parameter.\n\n```swift\nlet client = GotenbergClient(\n    baseURL: URL(string: ProcessInfo.processInfo.environment[\"GOTENBERG_URL\"] ?? \"http://localhost:7100\")!\n)\n```\n\n## Authentication\n\n### Basic Authentication\n\nGotenberg introduces basic authentication support starting from version [8.4.0](https://github.com/gotenberg/gotenberg/releases/tag/v8.4.0). Suppose you are running a Docker container using the command below:\n\n```bash\ndocker run --rm -p 3000:3000 \\\n-e GOTENBERG_API_BASIC_AUTH_USERNAME=gotenberg \\\n-e GOTENBERG_API_BASIC_AUTH_PASSWORD=password \\\ngotenberg/gotenberg:8 gotenberg --api-enable-basic-auth\n\n```\n\nTo integrate this setup with Chromiumly, you need to update your client instance as outlined below:\n\n\n```Swift\nlet client = GotenbergClient(\n    baseURL: URL(\n        string: ProcessInfo.processInfo.environment[\"GOTENBERG_URL\"] ?? \"http://localhost:7100\"\n    )!,\n    username: \"gotenberg\",\n    password: \"password\"\n)\n```\n\n### Advanced Authentication\n\nTo implement advanced authentication or add custom HTTP headers to your requests, you can use the `customHttpHeaders` option during initialization or for every function call. This allows you to pass additional headers, such as authentication tokens or custom metadata, with each API call.\n\nFor example, you can include a Bearer token for authentication along with a custom header as follows:\n\n```swift\nlet client = GotenbergClient(\n    baseURL: URL(\n        string: ProcessInfo.processInfo.environment[\"GOTENBERG_URL\"] ?? \"http://localhost:7100\"\n    )!\n)\n\nlet token = try await generateToken()\n\nlet response = try await client.convert(\n    url: URL(string: \"https://swift.org\")!,\n    clientHTTPHeaders: [\n        \"Authorization\": \"Bearer \\(token)\",\n        \"X-Custom-Header\": \"value\",\n    ]\n)\n\n```\n\n## Core Features\n\nGotenbergKit exposes different funcs that serve as wrappers to\nGotenberg's [routes](https://gotenberg.dev/docs/routes)\n\n### Chromium\n\n`GotenbergKit` client comes with a `convert` function that call one of Chromium's [routes](https://gotenberg.dev/docs/modules/chromium#routes) to convert `html`, `markdown` files, or a `url` to a `GotenbergResponse` which holds the content of the converted PDF file.\n\n`convert` expects two parameters; the first parameter represents what will be converted (i.e. `url`, `html`, or `markdown` files), and the second one is a `ChromiumOptions` parameter.\n\n#### URL\n\n```swfit\nlet response = try await client.convertUrl(\"https://gotenberg.dev/\")\n```\n\n```swift\nlet response = try await client.capture(url: URL(string: \"https://gotenberg.dev/\")!)\n```\n\n#### HTML\n\nThe only requirement is that one of the files name should be `index.html`.\n\n```swift\nlet index = try Data(contentsOf: URL(string:\"path/to/index.html\"))\nlet header = try Data(contentsOf: URL(string:\"path/to/header.html\"))\nlet response = try await client.convertHtml(\n    documents: [\n        \"index.html\": index,\n        \"header.html\": header\n    ]\n)\n```\n\n```swift\nlet response = try await client.capture(\n    htmlString: \"\u003chtml\u003eCONTENT\u003c/html\u003e\"\n)\n```\n\n#### Markdown\n\nThis route accepts an `index.html` file plus a markdown file.\n\n```swift\nlet html = \"\"\"\n\u003c!doctype html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003ctitle\u003eMy PDF\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    {{ toHTML \"file.md\" }}\n\u003c/body\u003e\n\"\"\"\nlet response = try await client.convertMarkdown(\n    files: [\n        \"index.html\": html.data(using: .utf8)!,\n        \"file.md\": \"Markdown Content\".data(using: .utf8)!\n    ]\n)\n\nlet response = try await client.capture(\n    html: html.data(using: .utf8)!,\n    markdown: \"Markdown Content\".data(using: .utf8)!\n)\n```\n\nEach `convert()` method takes an optional `properties` parameter of the following type which dictates how the PDF generated\nfile will look like.\n\n```swift\nChromiumOptions\n```\n\nIn addition to the `ChromiumOptions` customization options, the `convert()` method also accepts a set of parameters to further enhance the versatility of the conversion process.\n\n#### Screenshot\nSimilarly, the `capture()` function takes an optional `properties` parameter of the specified type, influencing the appearance of the captured screenshot file.\n\n```swift\nScreenshotOptions\n```\n\n### LibreOffice\n\nThe `LibreOffice` utility comes with a function called `convertWithLibreOffice`. This function interacts with [LibreOffice](https://gotenberg.dev/docs/routes#convert-with-libreoffice) route to convert different documents to PDF files. You can find the file extensions\naccepted [here](https://gotenberg.dev/docs/routes#convert-with-libreoffice).\n\n```swift\nlet response = try await client.convertWithLibreOffice(\n    urls: [\n        .init(url: \"https://someurl.com/myfile.csv\"),\n        .init(url: \"https://someurl.com/myfile.odt\"),\n        .init(url: \"https://someurl.com/myfile.doc\"),\n        .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n)\n```\n\nSimilarly to Chromium's route `convert` function, this function takes the following optional parameters :\n\n```swift\nLibreOfficeConversionOptions\n```\n\nNote: not setting merge to true will return a zip file containing all PDF files\n\n### PDF Engines\n\nThe `PDFEngines` funcs interacts with Gotenberg's [PDF Engines](https://gotenberg.dev/docs/routes#convert-into-pdfa--pdfua-route) routes to manipulate PDF files.\n\n#### Format Conversion\n\nThis function interacts with [PDF Engines](https://gotenberg.dev/docs/routes#convert-into-pdfa--pdfua-route) convertion route to transform PDF files into the requested PDF/A format and/or PDF/UA.\n\n```swift\nlet response = try await client.convertWithPDFEngines(\n    documents: [\n        \"file_1.pdf\": Data,\n        \"file_2.pdf\": Data\n    ],\n    options: PDFEngineOptions(\n        pdfua: true,\n        format: .A1B\n    )\n)\n\nlet response = try await client.convertWithPDFEngines(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n    options: PDFEngineOptions(\n        pdfua: true,\n        format: .A1B\n    )\n)\n```\n\n#### Merging\n\nThese functions interact with [PDF Engines](https://gotenberg.dev/docs/routes#merge-pdfs-route) merge route which gathers different\nengines that can manipulate and merge PDF files such\nas: [PDFtk](https://gitlab.com/pdftk-java/pdftk), [PDFcpu](https://github.com/pdfcpu/pdfcpu), [QPDF](https://github.com/qpdf/qpdf),\nand [UNO](https://github.com/unoconv/unoconv).\n\n```swift\nlet response = try await client.mergeWithPDFEngines(\n    documents: [\n        \"file_1.pdf\": Data,\n        \"file_2.pdf\": Data\n    ],\n    options: PDFEngineOptions(\n        pdfua: true,\n        format: .A1B\n    )\n)\n\nlet response = try await client.mergeWithPDFEngines(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n    options: PDFEngineOptions(\n        pdfua: true,\n        format: .A1B\n    )\n)\n```\n\n#### Metadata Management\n\n##### readMetadata\n\nThis function reads metadata from the provided PDF files.\n\n```swift\nlet response = try await client.readPDFMetadata(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n)\n\nlet response = try await client.readPDFMetadata(\n    documents: [\n        \"file_1.pdf\": Data,\n        \"file_2.pdf\": Data\n    ]\n)\n```\n\n##### writeMetadata\n\nThis function writes metadata to the provided PDF files.\n\n```swift\nlet response = try await client.writePDFMetadata(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n    metadata: [\n        \"Author\": \"Stevenson Michel\",\n        \"Title\": \"GotenbergKit\"\n        \"Keywords\": [\"pdf\"', \"gotenberg\", \"swift\"]\n    ]\n)\n```\n\nReferr to [ExifTool](https://exiftool.org/TagNames/XMP.html#pdf) for a comprehensive list of accessible metadata options.\n\n### PDF Splitting\n\nEach [Chromium](#chromium) and [LibreOffice](#libreoffice) route has a `split` parameter that allows splitting a PDF file into multiple files. The `split` parameter is an object with the following properties:\n\n- `mode`: the mode of the split. It can be `pages` or `intervals`.\n- `span`: the span of the split. It is a string that represents the range of pages to split.\n- `unify`: a boolean that allows unifying the split files. Only works when `mode` is `pages`.\n- `flatten`: a boolean that, when set to true, flattens the split PDF files, making form fields and annotations uneditable.\n\n```swift\nlet response = try await client.convertUrl(\n    url: URL(string: \"https://gotenberg.dev\")!,\n    options: ChromiumOptions(\n        mode: .pages,\n        span: \"1-2\",\n        unify: true,\n    ),\n)\n```\n\nOn the other hand, PDFEngines' has a `split` function that interacts with [PDF Engines](https://gotenberg.dev/docs/routes#split-pdfs-route) split route which splits PDF files into multiple files.\n\n```swift\nlet response = try await client.splitPDF(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ],\n    options: SplitPDFOptions(\n        splitMode: .pages,\n        splitSpan: \"1-2\",\n        splitUnify: true,\n    ),\n)\n```\n\n\u003e ⚠️ **Note**: Gotenberg does not currently validate the `span` value when `mode` is set to `pages`, as the validation depends on the chosen engine for the split feature. See [PDF Engines module configuration](https://gotenberg.dev/docs/configuration#pdf-engines) for more details.\n\n### PDF Flattening\n\nPDF flattening converts interactive elements like forms and annotations into a static PDF. This ensures the document looks the same everywhere and prevents further edits.\n\n```swift\n\nlet response = try await client.flattenPDF(\n    urls: [\n       .init(url: \"https://someurl.com/myfile.pdf\")\n    ]\n)\n```\n\n#### File Generation\n\n`client.writeToFile` is just a complementary function that takes the `GotenbergResponse` returned by any functions beside readPDFMetadata, and a\nchosen `filepath` with name to generate a PDF file or zip file. Note that note that this function will not create sub directories if not already exist.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoven87%2Fgotenberg-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthoven87%2Fgotenberg-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoven87%2Fgotenberg-kit/lists"}