Publishing & Review

Understand risk tiers, review SLAs, auto-listing criteria, and the full lifecycle from submission to publication.

Risk Tiers

Every package is assigned a risk tier that determines its review path, SLA, and listing behavior. Choose the tier that matches the highest-risk capability in your package.

Auto-Listing Criteria

Packages in the data_only tier can be automatically listed in the catalog without manual review, provided all of the following criteria are met:

• Conformance score: ≥ 80/100 across all 6 dimensions
• No breaking drift: If this is an update, zero breaking changes detected against the previous published version
• Documentation complete: All capabilities have descriptions, parameter documentation, and at least one example payload
• Security baseline: HTTPS enforced, no credential leakage detected, webhook signatures verified
• Account standing: Developer account in good standing (no active suspensions or policy violations)

Auto-listing typically completes within 5 minutes of submission. If any criterion fails, the package enters the manual review queue at the action_capable SLA tier.

Manual Review Process

Packages that require manual review are evaluated by the Aiffinity Platform Review Team. The process varies by risk tier:

Risk Tier	Reviewer	SLA	Includes
action_capable	Platform reviewer	48 hours	Conformance validation, action safety check, error handling review
high_trust	Senior reviewer + security engineer	5 business days	Everything above + security audit, data handling review, compliance check
strategic_surface	Senior reviewer + platform architect	5 business days	Everything above + architecture review, surface integration testing, UX evaluation

Review workflow

1. Submission: You submit the package version via the API or developer console. Status changes to in_review.
2. Assignment: The package is assigned to a reviewer within 4 hours. You receive an email notification with the reviewer's timeline.
3. Evaluation: The reviewer runs the conformance suite independently, exercises capabilities manually, and inspects code behavior against the review checklist.
4. Feedback: If issues are found, the reviewer returns the package with detailed feedback. Status changes to changes_requested.
5. Resubmission: After addressing feedback, you resubmit the version. It re-enters the queue but receives priority processing (typically within 24 hours).
6. Approval: Once all criteria are met, the reviewer approves the package. Status changes to approved.
7. Publication: You publish the approved version to make it available in the catalog.

Review Checklist

Reviewers evaluate packages against the following criteria. Use this as a self-assessment before submitting.

Category	Criteria	Required For
Security Audit	No credential leakage in responses, HTTPS enforced, webhook signatures verified, tokens properly scoped	All tiers
Capability Contracts	All declared capabilities respond correctly, schema matches actual responses, refresh intervals are honored	All tiers
Error Handling	Correct error envelope format, graceful degradation on upstream failures, appropriate retry headers	All tiers
Documentation Quality	Clear capability descriptions, parameter docs, example payloads, changelog for updates	All tiers
Performance Benchmarks	p50 latency < 500ms, p99 latency < 2s, payload size within limits	All tiers
Action Safety	Destructive actions require confirmation, idempotency keys supported, rate limiting in place	action_capable+
Data Handling	PII minimization, encryption at rest, data retention policies, GDPR/CCPA compliance	high_trust+
Architecture Review	Surface guidance correctness, widget rendering compatibility, cross-package coordination safety	strategic_surface

Appeal Process

If your package is rejected and you believe the decision was incorrect, you can file an appeal.

How to appeal

1. Navigate to the rejected version in the developer console
2. Click "Appeal Decision" and provide a detailed explanation addressing each rejection reason
3. Include supporting evidence: updated tests, documentation, or code changes that address the concerns

Appeal timeline

• Appeals must be filed within 30 days of the rejection
• A different reviewer is assigned to evaluate the appeal
• Appeal decisions are returned within 5 business days
• Appeal decisions are final. If the appeal is denied, you must address the feedback and resubmit as a new version.

// Check appeal status via SDK
const appeal = await client.packages.getAppealStatus(packageId, versionId);

console.log(`Appeal status: ${appeal.status}`);
// 'pending' | 'under_review' | 'approved' | 'denied'

if (appeal.status === 'denied') {
  console.log(`Reason: ${appeal.decision.reason}`);
  console.log(`Feedback: ${appeal.decision.feedback}`);
}

Version Management

Packages follow semantic versioning. Each version goes through its own review cycle independently.

Creating a new version

const version = await client.packages.createVersion(packageId, {
  capabilities: updatedCapabilities,
  changelog: 'Added 3-day forecast support and improved error handling',
});

console.log(`Created version ${version.number} (${version.id})`);
// Created version 1.2.0 (ver_abc123)

Deprecation flow

When you release a new version, you can deprecate older versions to guide users toward the latest release:

1. Mark as deprecated: The version remains functional but shows a deprecation notice. Users see a prompt to update.
2. Set sunset date: Specify when the version will stop functioning. Minimum sunset window is 90 days from the deprecation date.
3. Notify users: Aiffinity automatically notifies all users who have the deprecated version installed.

// Deprecate an old version
await client.packages.deprecateVersion(packageId, oldVersionId, {
  reason: 'Superseded by v2.0 with improved forecast accuracy',
  sunsetDate: '2026-09-01T00:00:00Z',  // minimum 90 days out
  migrationGuide: 'https://docs.acmeweather.com/migration/v1-to-v2',
});

Sunset policy

• Deprecated versions continue to function normally until the sunset date
• 30 days before sunset, users receive a final migration reminder
• On the sunset date, capability requests return a 410 Gone response
• Sunset versions are removed from the catalog but remain accessible in the developer console for historical reference

Suspension & Reinstatement

Packages or developer accounts may be suspended for policy violations. Suspensions are rare and only applied after investigation.

Reasons for suspension

• Security incident: Credential leakage, unauthorized data access, or unpatched vulnerabilities reported and unaddressed for > 72 hours
• Terms violation: Misuse of user data, deceptive capability descriptions, or undisclosed data collection
• Reliability failure: Sustained error rate > 50% for more than 24 hours with no acknowledgment or remediation
• Abuse: Excessive API usage beyond documented limits, spam, or malicious payloads

Notification

When a package is suspended, you receive:

• An email to your registered developer contact with the suspension reason and specific findings
• A webhook event (package.suspended) to your registered webhook endpoint
• A banner in the developer console on the affected package page

Remediation and reinstatement

1. Review the suspension notice and address all cited issues
2. Submit a remediation report through the developer console describing what was fixed
3. The review team evaluates the remediation within 3 business days
4. If approved, the package is reinstated and users are notified of the restoration
5. A second suspension for the same issue results in permanent removal from the catalog

Publishing Checklist

Use this checklist before submitting your package to ensure a smooth review process.

	Item	Details
✓	Conformance score	Run the full conformance suite and confirm a score ≥ 80/100
✓	Risk tier selection	Verify your tier matches the highest-risk capability in the package
✓	Capability descriptors	All capabilities have complete schemas, descriptions, and surface guidance
✓	Error handling	All error responses follow the standard envelope format with correct status codes
✓	Security baseline	HTTPS enforced, webhook signatures configured, no secrets in responses
✓	Performance	p50 < 500ms, p99 < 2s, payload sizes within limits
✓	Documentation	Parameter descriptions, example payloads, and a changelog for updates
✓	Golden fixtures	At least 3 test fixtures covering happy path, edge case, and error scenario
✓	Drift check	For updates: run drift detection against the previous version, resolve any breaking changes
✓	Listing metadata	Package name, description, icon, category, and support contact are complete