@skippy-id/sdk

Node-first SDK for interacting with Skippy projects, templates, organisations, and OpenID VC flows.

Installation

npm install @skippy-id/sdk

Usage

import { Skippy } from '@skippy-id/sdk';

const skippy = new Skippy({
	apiKey: process.env.SKIPPY_API_KEY!,
	baseUrl: 'https://api.skippy.id/ext-api',
	request: {
		timeoutMs: 10000,
		retry: {
			maxRetries: 2,
			retryDelayMs: 250,
			retryMethods: ['get']
		}
	}
});

const organisation = await skippy.organisation.getOrganisation('org_123');
const templates = await skippy.template.getAllCredentialTemplates('project_123');

Security

• Production baseUrl values must use approved Skippy API hosts such as https://api.skippy.id/ext-api or https://staging.skippy.id/ext-api.
• Local localhost overrides are accepted only in development or test environments.
• SDK errors expose typed status plus sanitized metadata such as code, requestId, and retryAfter; raw upstream response bodies and transport internals are not surfaced.
• Security reports for this repository should follow the policy in https://github.com/Skippy-Id/skippy/blob/main/SECURITY.md.

Modules

• project: project creation, lookup, update, and listing.
• template: credential and presentation template operations.
• organisation: organisation lookup, update, and organisation user listing.
• openidvc: credential offer and authorization request helpers for API-key routes.

Validation

npm run release:check -w packages/skippy-ts-sdk
npm run test:coverage -w packages/skippy-ts-sdk

Publishing Workflow

The repository includes a dedicated GitHub Actions workflow at .github/workflows/publish-skippy-sdk.yml.

The recommended publish path is npm trusted publishing with GitHub OIDC, which avoids expiring 90-day write tokens.

Use this release flow:

1. Run one command from the repo root:
   • npm run sdk:release -- patch
   • npm run sdk:release -- minor
   • npm run sdk:release -- major
   • npm run sdk:release -- 1.0.2
2. Push the release commit and tag:
   • git push origin HEAD --follow-tags
3. In npm package settings for @skippy-id/sdk, add a trusted publisher for:
   • GitHub organization or user: Skippy-Id
   • Repository: skippy
   • Workflow filename: publish-skippy-sdk.yml
4. Publish with either:
   • a pushed git tag in the format sdk-vX.Y.Z, or
   • manual workflow_dispatch using a source_ref.

The workflow will:

• install dependencies
• run npm run release:check -w packages/skippy-ts-sdk
• run npm pack --dry-run -w packages/skippy-ts-sdk
• verify the package version is not already published
• publish @skippy-id/sdk to npm using GitHub OIDC trusted publishing

Notes:

• id-token: write is already enabled in the workflow for OIDC.
• npm trusted publishing requires GitHub-hosted runners.
• npm currently requires Node 22.14+ and npm CLI 11.5.1+ for trusted publishing, so the workflow uses Node 24.
• If the package ever needs private npm dependencies during install, use a separate read-only npm token only for install steps, not for publishing.
• npm run sdk:release:dry-run previews bump + commit + tag actions without changing files.
• npm run sdk:release -- patch performs bump + release-file commit + matching sdk tag in one flow.
• npm run sdk:version -- --dry-run patch previews the next SDK version without changing files.
• npm run sdk:tag:dry-run previews the exact sdk-vX.Y.Z tag for the current SDK version.
• The combined release script still keeps sdk:version and sdk:tag available when you want manual control.
• Keep baseUrl pointed at official Skippy hosts in production. Arbitrary remote endpoints are intentionally rejected by the SDK.