readpst 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip van Burleigh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# readpst
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert Outlook `.pst` (and `.ost`) files to `.eml` files from Node.js, using [libpst](https://www.five-ten-sg.com/libpst/)'s `readpst`.
+
+## Install
+
+The `readpst` binary must be on your `PATH`:
+
+```sh
+brew install libpst      # macOS
+apt install pst-utils    # Debian/Ubuntu
+apk add libpst           # Alpine
+```
+
+```sh
+npm install readpst
+```
+
+## Usage
+
+```js
+import { extract } from "readpst";
+
+const files = await extract("mailbox.pst", { outDir: "out" });
+// ["/abs/out/Inbox/1.eml", "/abs/out/Sent Items/1.eml", ...]
+```
+
+`outDir` mirrors the PST's folder tree, with one RFC 822 `.eml` per message and attachments kept inline as MIME parts. Text is written as UTF-8.
+
+### Options
+
+| Option        | Default       | Description                                                       |
+| ------------- | ------------- | ----------------------------------------------------------------- |
+| `outDir`      | (required)    | Output directory, created if missing                              |
+| `types`       | `["email"]`   | Any of `"email"`, `"appointment"`, `"journal"`, `"contact"`       |
+| `readpstPath` | `"readpst"`   | Path to the binary                                                |
+
+`readpst` needs a seekable file on local disk, so download a remote PST to a temp file first. Cleaning up `outDir` is up to you.
+
+## License
+
+MIT. libpst itself is GPL-2.0; this package only runs it as a separate program and does not bundle it.

package/index.d.ts

@@ -0,0 +1,13 @@
+export type ItemType = "email" | "appointment" | "journal" | "contact";
+
+export interface ExtractOptions {
+  /** Directory to write into. Created if missing; mirrors the PST's folder tree. */
+  outDir: string;
+  /** Item types to export. Defaults to ["email"]. */
+  types?: ItemType[];
+  /** Path to the readpst binary. Defaults to "readpst" on PATH. */
+  readpstPath?: string;
+}
+
+/** Converts a .pst/.ost into one .eml per item and resolves to the absolute paths of the written files. */
+export function extract(pstPath: string, options: ExtractOptions): Promise<string[]>;

package/index.js

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+import { mkdir, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+const TYPE_CODES = { email: "e", appointment: "a", journal: "j", contact: "c" };
+
+export async function extract(pstPath, { outDir, types = ["email"], readpstPath = "readpst" }) {
+  const dir = resolve(outDir);
+  await mkdir(dir, { recursive: true });
+
+  const typeCodes = types.map((type) => {
+    if (!TYPE_CODES[type]) throw new Error(`Unknown item type "${type}"`);
+    return TYPE_CODES[type];
+  });
+
+  try {
+    await run(readpstPath, ["-e", "-8", "-q", "-t", typeCodes.join(","), "-o", dir, resolve(pstPath)]);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(
+        `"${readpstPath}" not found. Install libpst: brew install libpst, apt install pst-utils or apk add libpst`
+      );
+    }
+    throw new Error(`readpst failed: ${(error.stderr || error.stdout)?.trim() || error.message}`, { cause: error });
+  }
+
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name));
+}

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "readpst",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Convert Outlook .pst files to .eml files with libpst's readpst",
+  "keywords": ["pst", "ost", "outlook", "eml", "email", "readpst", "libpst"],
+  "author": "Philip van Burleigh",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "types": "./index.d.ts",
+    "default": "./index.js"
+  },
+  "files": ["index.js", "index.d.ts"],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}