Prepare the TypeScript SDK for npm packaging and maintainer-controlled publishing

[divyanshim27]

Summary

The TypeScript SDK is currently a private, source-only workspace package. External consumers must clone the repository or install it from a local path, so it is not yet usable as a normal versioned dependency.

Prepare the SDK for public npm distribution and a maintainer-controlled release process. The first live publish must remain a maintainer action because it requires control of the npm scope and registry trust configuration.

Current behavior

• The package is marked private.
• Its export points directly to TypeScript source.
• The build command performs type-checking but emits no JavaScript or declaration files.
• A package dry run currently includes tests, fixtures, examples, source files, and the SDK lockfile.
• The documented installation path is local-only.
• @microai/paygate-sdk is not currently present in the public npm registry, but registry availability does not prove that this repository controls the @microai scope.

Desired behavior

The SDK should produce a minimal, versioned package containing compiled ESM JavaScript, TypeScript declarations, package metadata, its README, and license information. A clean consumer project should be able to install the packed artifact and import the public API without referencing repository source files.

Publishing should happen only through a maintainer-approved release process after the package name and npm scope ownership are confirmed. Prefer npm trusted publishing with short-lived OIDC credentials over a long-lived write token.

Maintainer prerequisites

Before implementation is approved, a maintainer must:

• confirm the final npm package name and ownership of its scope;
• decide whether the first release will be direct or staged;
• configure the npm trusted publisher and any protected GitHub release environment;
• confirm who is authorized to create SDK releases and version tags.

Key interfaces

• SDK package metadata — public name, version, files, module exports, declaration entry, repository metadata, license, and public access configuration.
• TypeScript build configuration — emit distributable ESM JavaScript and .d.ts files into a clean output directory.
• SDK CI — keep type-checking and unit tests, and add package-content and clean-consumer checks.
• Release workflow — publish only from an explicit maintainer-controlled release event with least-privilege permissions.
• SDK and root documentation — distinguish local development from installation of an actually published version.

Acceptance criteria

• The maintainer-approved package name is used and the package is no longer marked private.
• The build produces ESM JavaScript and TypeScript declarations without publishing repository source or test files.
• Package exports and type declarations resolve from the generated distribution directory.
• npm pack --dry-run contains only the intended runtime package files, README, license, and required metadata.
• CI installs the packed tarball into a clean temporary consumer project and verifies that the public SDK API imports and type-checks.
• Existing SDK unit tests and type checks continue to pass.
• The release workflow uses a maintainer-approved npm publishing mechanism and least-privilege GitHub permissions; it does not introduce a long-lived write token when trusted publishing is available.
• Documentation switches to the registry install command only after the package has actually been published.
• The first release is performed and verified by a maintainer, including the registry page and install command.

Out of scope

• Changing the x402-style protocol, gateway behavior, receipt format, or SDK public behavior.
• Publishing from pull requests or contributor forks.
• Automatically deciding the npm scope or creating registry ownership on behalf of maintainers.
• Requiring a changelog format before the repository has chosen a release/versioning policy.

Verification

Run the SDK type checks and tests, build from a clean checkout, inspect npm pack --dry-run, and install the resulting tarball in a temporary consumer project. The release workflow must also be reviewed without performing an unapproved publication.

Blocked by

Maintainer confirmation of the npm package name/scope and release authorization model.

[github-actions]

Assigned @divyanshim27 based on the issue request.

[AnkanMisra]

@divyanshim27, the underlying issue is valid, but I updated the scope because publishing is more than adding a workflow. The SDK currently emits no distributable files, exports TypeScript source, and packages tests and fixtures. The npm scope and release credentials also require maintainer ownership, so those parts cannot be completed safely from a contributor PR alone.

You can still work on the package-readiness portion once the final package name and npm scope are confirmed: produce compiled JavaScript and declarations, restrict the tarball contents, add a clean-consumer install/import test, and prepare the maintainer-controlled release workflow. Please wait for confirmation of the npm scope and release model before starting, and do not add a long-lived npm write token.