readpst 0.0.0-stage → 0.2.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,60 @@
-# 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", ...]
+```
+
+### Without managing files
+
+`read` extracts into a temp dir, yields each item and removes the dir when the loop ends (also on `break` or a thrown error):
+
+```js
+import { read } from "readpst";
+
+for await (const item of read("mailbox.pst")) {
+  item.path;             // "Inbox/1.eml"
+  await item.buffer();   // Buffer
+  item.stream();         // fs.ReadStream, e.g. to upload to S3
+}
+```
+
+Consume each item's buffer or stream before moving to the next one; the files are gone once the loop finishes.
+
+### Writing to a directory
+
+`extract` writes to a directory you own and returns the file paths. `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)    | `extract` only: 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. With `extract`, 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,26 @@
+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[]>;
+
+export interface PstItem {
+  /** Path relative to the PST root, e.g. "Inbox/1.eml". */
+  path: string;
+  buffer(): Promise<Buffer>;
+  stream(): import("node:fs").ReadStream;
+}
+
+/**
+ * Extracts into a temp dir and yields each item; the dir is removed when the loop ends, breaks or throws.
+ * Read an item's buffer or stream before moving to the next one.
+ */
+export function read(pstPath: string, options?: Omit<ExtractOptions, "outDir">): AsyncGenerator<PstItem, void, undefined>;

package/index.js

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative, 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));
+}
+
+export async function* read(pstPath, options = {}) {
+  const dir = await mkdtemp(join(tmpdir(), "readpst-"));
+  try {
+    for (const file of await extract(pstPath, { ...options, outDir: dir })) {
+      yield { path: relative(dir, file), buffer: () => readFile(file), stream: () => createReadStream(file) };
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}

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.2.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"
+  }
+}