Submission (Certified Plugins)

This is the flow for publishing a CERTIFIED plugin built by a third party on the marketplace. It doesn't apply to OFFICIAL plugins built by niyase itself, which ship through a separate internal release path (auto-approved).

@niyase/plugin-sdk is already published to npm under the MIT license. You can start developing from outside this monorepo with npm install @niyase/plugin-sdk or npx @niyase/plugin-sdk new (see Setup).

STEP 1: Register as a developer

On the marketplace developer portal (marketplace.niyase.com/developer; once logged in, /me), register a developer profile (display name, slug).

STEP 2: Claim a namespace

Claim the @scope part (the namespace) of your plugin ID. To submit @your-org/tasks, you must own @your-org (first come, first served; @niyase is reserved for official plugins).

STEP 3: Issue a publishing token (PAT)

On the developer portal, issue a Personal Access Token (PAT) with plugin.* scopes. It uses the same issuance mechanism as a regular personal access token, but the credential classes are strictly separated: a token scoped to plugin.* only cannot call the regular API — it can only reach the developer-portal-specific routes.

Scope	Use
plugin.publish	Create and submit applications
plugin.read.stats	View install statistics
plugin.manage	Manage profile and namespaces

An expiry is required: 90 days by default, 365 days at most (you cannot issue a token with no expiry). Issuing from the developer portal UI grants plugin.publish + plugin.read.stats by default. If you need plugin.manage or a different expiry, call the API directly. You cannot use a PAT to issue another PAT — issuing requires an active session login.

STEP 4: Submit

The CLI handles build, validation, and submission all at once.

NIYASE_TOKEN=<your plugin.publish PAT> niyase-plugin publish
# ✓ built (sha256 …)
# ✓ manifest validation OK (@your-org/tasks)
# ✓ application submitted (submission ..., state=SUBMITTED)

Internally, publish performs: build → validateManifest() → create application (DRAFT) → upload bundle (multipart, with sha256) → request review (SUBMITTED). Adding --dry-run stops after build and validation (it never touches the network). The token is resolved in order from --token / NIYASE_TOKEN / ~/.niyaserc, and the target defaults to https://api.niyase.com (override with --registry / NIYASE_REGISTRY).

Publishing requirements

To be eligible for review, a submission must meet all of the following:

• The plugin ID follows @namespace/name (e.g. @your-company/your-plugin)
• The manifest specifies a niyase category
• displayName / description are clear and free of exaggerated claims
• The license is stated explicitly (an OSS license such as MIT or Apache 2.0, or a commercial license)
• If the plugin calls an external API, the destination and the purpose of the data it collects are disclosed
• User data handling is consistent with a privacy policy

STEP 5: Review → publication

The application advances through a state machine (plugin_submission.state). The label in parentheses is what the developer portal displays.

DRAFT → SUBMITTED → IN_REVIEW
  → { CHANGES_REQUESTED | APPROVED | REJECTED }
CHANGES_REQUESTED → SUBMITTED (fix and resubmit)
APPROVED → PUBLISHED
{DRAFT | SUBMITTED | IN_REVIEW | CHANGES_REQUESTED} → WITHDRAWN

PUBLISHED, REJECTED, and WITHDRAWN are terminal. A version update is created as a new application and goes through review again.

niyase staff review the manifest and the bundle (via a signed URL), and approve → publish lists it on the marketplace. If changes are requested, it's sent back with comments, and you can fix it and resubmit. You can withdraw an application at any point while it's in progress. Track submission status from the developer portal dashboard.

OFFICIAL plugins (niyase's own @niyase/* plugins) are auto-approved and released through a separate internal script. Because CERTIFIED plugins are third-party code, they always go through human review.

Execution model

The plugin development company hosts its own server-side processing on its own infrastructure — niyase doesn't provide compute for certified plugins. What niyase does provide:

Provided	Description
Webhooks	Notify your server of plugin events
API key auth	Tokens for authenticating your server
Callback API	Your server reports results back to niyase
Generic CRUD API	Read/write your plugin's own tables (Core API Integration)
Bundle distribution	Proxied from GCS. The sha256 is re-verified at load time (a mismatch is refused)

Published bundles run in a separate execution context on each platform — a sandboxed iframe on cloud, <webview> on desktop, and a React Native WebView on mobile (none of them can touch the host's cookies or localStorage; communication is limited to the bridge). This isn't cloud-only — all three apps (cloud, desktop, mobile) get the same distribution.

Not available yet (until GA)

• Direct connections from your plugin to your own server: a path for the plugin's browser-side UI to fetch your own server directly (the niyase.partner proxy) won't ship until GA. The bridge only exposes niyase.data / niyase.core to browser-side code. If you need to talk to your own backend, do it server-to-server — your server calling niyase's callback API, not the other way around.
• Custom domain: developer.niyase.com is a vanity domain planned for the marketplace at GA. For now, use the developer portal inside marketplace (marketplace.niyase.com/developer).

After publication

• Version updates are re-reviewed as new applications
• Check install counts and application status on the developer portal dashboard
• Integrity: the distributed bundle is checked against the sha256 recorded at upload time; if they don't match, it isn't delivered