TypeScript SDK

Automate package distribution from your product, CI, and internal tools.

Use @packagepass/sdk when registry access belongs inside an onboarding flow, customer workspace lifecycle, release pipeline, or generated-code publishing system.

install

npm install @packagepass/sdk

# or
pnpm add @packagepass/sdk
bun add @packagepass/sdk

Create a client

client.ts

import { PackagePassClient } from "@packagepass/sdk";

export const packagepass = new PackagePassClient({
  apiKey: process.env.PACKAGEPASS_API_KEY!,
  tenant: "acme",
  apiUrl: "https://api.preview.packagepass.dev/v1",
  registryUrl: "https://registry.preview.packagepass.dev/npm/",
  userAgent: "acme-control-plane/1.0"
});

Tenant header

The tenant option sends x-packagepass-tenant on API calls. You can also pass tenantId to many resource methods.

Custom fetch

Pass fetch when running in a framework, worker runtime, test harness, or environment that wraps outbound requests.

Packages

Create packages and publish tarballs

The SDK publish methods expect the already-built package manifest and tarball bytes. Use the CLI when you want PackagePass to run npm pack for you.

create package

await packagepass.packages.create({
  name: "@acme/payments",
  visibility: "private",
  description: "Customer payments SDK"
});

publish tarball

import { readFile } from "node:fs/promises";

const manifest = JSON.parse(
  await readFile("packages/payments/package.json", "utf8")
);
const tarball = await readFile("acme-payments-4.8.0.tgz");

await packagepass.versions.publishTarball({
  packageName: "@acme/payments",
  version: manifest.version,
  tag: "latest",
  manifest,
  tarball
});

Publish preview builds

preview

const preview = await packagepass.previews.publishTarball({
  packageName: "@acme/auth",
  channel: "pr-482",
  manifest,
  tarball,
  provenance: {
    pullRequest: 482,
    commit: process.env.GITHUB_SHA
  }
});

console.log(preview.install.npm);

Preview result

A preview publish returns the generated version, the preview-<channel> tag, and install commands for npm and Bun.

Access

Grant access and mint tokens

Use grants for policy and tokens for credentials. Install tokens should be short-lived and scoped to the smallest package and subject possible.

grant customer install

await packagepass.grants.create({
  subject: { type: "customer", slug: "globex" },
  resource: { type: "package", name: "@acme/payments" },
  actions: ["package:install"],
  conditions: {
    expiresAt: "2026-05-26T00:00:00.000Z"
  }
});

create install token

const token = await packagepass.tokens.createInstallToken({
  name: "globex payments install",
  subject: { type: "customer", slug: "globex" },
  resources: [{
    type: "package",
    name: "@acme/payments",
    actions: ["package:install"]
  }],
  expiresAt: new Date(Date.now() + 30 * 864e5).toISOString()
});

Generate installer config

install config

const config = await packagepass.config.generateInstallConfig({
  scope: "@acme",
  manager: "npm",
  tokenEnvVar: "PACKAGEPASS_TOKEN"
});

console.log(config.file);
console.log(config.content);

Policy, audit, and validation

policy

await packagepass.policy.explain({
  subject: { type: "user", email: "alice@example.com" },
  action: "package:install",
  resource: { type: "package", name: "@acme/payments" }
});

audit

await packagepass.audit.listEvents({
  packageName: "@acme/payments",
  type: "package.downloaded",
  limit: 50
});

validation

await packagepass.validation.validateManifest({
  name: "@acme/payments",
  version: "4.8.0",
  type: "module",
  types: "./dist/index.d.ts"
});

Handle errors

PackagePassError

import { PackagePassError } from "@packagepass/sdk";

try {
  await packagepass.packages.get("@acme/payments");
} catch (error) {
  if (error instanceof PackagePassError) {
    console.error(error.status);
    console.error(error.code);
    console.error(error.requestId);
    console.error(error.details);
  }
}

Keep the request ID

API errors include a request ID. Log it with the error code and status so a failed publish, grant, or install can be traced through audit and server logs.

SDK resource reference

Resource	Methods	Use
`packagepass.tenants`	create, list	Tenant administration and bootstrap setup.
`packagepass.scopes`	create, list	Create npm scopes and read their registry URLs.
`packagepass.packages`	create, list, get, update, archive	Manage package metadata and lifecycle.
`packagepass.versions`	publishTarball, list, get, deprecate, yank, listDistTags, setDistTag, deleteDistTag	Publish release tarballs and manage release metadata.
`packagepass.previews`	publishTarball, list	Publish preview artifacts and read active preview versions.
`packagepass.grants`	create, list, revoke	Grant and revoke subject access.
`packagepass.subjects`	customers, agents, groups	Create, list, update, and delete product identities used in grants and tokens.
`packagepass.tokens`	createApiToken, createInstallToken, exchangeCiToken, list, revoke	Mint, exchange, audit, and revoke scoped credentials.
`packagepass.config`	generateInstallConfig	Generate .npmrc or bunfig.toml content.
`packagepass.policy`	explain	Debug an authorization decision for a subject and resource.
`packagepass.audit`	listEvents	Read audit events for packages and tenant operations.
`packagepass.validation`	validateManifest	Run package policy validation before publishing.

Subject and action types

Subject	Use
`user:alice@example.com`	A person identified by email.
`customer:globex`	A customer account or tenant in your product.
`agent:code-reviewer`	A non-human actor such as an AI agent, service, or CI job.
`group:platform`	A team or group.

package:read

package:install

package:publish

package:deprecate

package:yank

package:manage_dist_tags

grant:manage

token:mint

audit:read

The SDK re-exports shared PackagePass types such as SubjectRef, ResourceRef, PackageAction, RegistryPackage, RegistryVersion, and PackagePassError. See the API reference for endpoint-level details.