ObjectStackObjectStack

Developer Portal

Developer Portal protocol schemas

Developer Portal Protocol

Defines schemas for the developer-facing side of the marketplace ecosystem.

Covers the complete developer journey:


Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate

Architecture Alignment

  • Salesforce Partner Portal: ISV registration, AppExchange publishing, Trialforce

  • Shopify Partner Dashboard: App management, analytics, billing

  • VS Code Marketplace Management: Extension publishing, statistics, tokens

Identity Integration (better-auth)

Authentication, organization management, and API keys are handled by the

Identity module (@objectstack/spec Identity namespace), which follows the

better-auth specification. This module only defines marketplace-specific

extensions on top of the shared identity layer:

  • User & Session → Identity.UserSchema, Identity.SessionSchema

  • Organization & Members → Identity.OrganizationSchema, Identity.MemberSchema

  • API Keys → Identity.ApiKeySchema (with marketplace scopes)

Key Concepts

  • Publisher Profile: Links an Identity Organization to a marketplace publisher

  • App Listing Management: CRUD for marketplace listings (draft → published)

  • Version Channels: alpha / beta / rc / stable release channels

  • Publishing Analytics: Install trends, revenue, ratings over time

Source: packages/spec/src/cloud/developer-portal.zod.ts

TypeScript Usage

import { AnalyticsTimeRange, CreateListingRequest, ListingActionRequest, PublisherProfile, PublishingAnalyticsRequest, PublishingAnalyticsResponse, ReleaseChannel, TimeSeriesPoint, UpdateListingRequest, VersionRelease } from '@objectstack/spec/cloud';
import type { AnalyticsTimeRange, CreateListingRequest, ListingActionRequest, PublisherProfile, PublishingAnalyticsRequest, PublishingAnalyticsResponse, ReleaseChannel, TimeSeriesPoint, UpdateListingRequest, VersionRelease } from '@objectstack/spec/cloud';

// Validate data
const result = AnalyticsTimeRange.parse(data);

AnalyticsTimeRange

Allowed Values

  • last_7d
  • last_30d
  • last_90d
  • last_365d
  • all_time

CreateListingRequest

Properties

PropertyTypeRequiredDescription
packageIdstring✅Package identifier
namestring✅App display name
taglinestringoptional
descriptionstringoptional
categorystring✅Marketplace category
tagsstring[]optional
iconUrlstringoptional
screenshotsObject[]optional
documentationUrlstringoptional
supportUrlstringoptional
repositoryUrlstringoptional
pricingEnum<'free' | 'freemium' | 'paid' | 'subscription' | 'usage-based' | 'contact-sales'>✅
priceInCentsintegeroptional

ListingActionRequest

Properties

PropertyTypeRequiredDescription
listingIdstring✅Listing ID
actionEnum<'submit' | 'unlist' | 'deprecate' | 'reactivate'>✅Action to perform on listing
reasonstringoptional

PublisherProfile

Properties

PropertyTypeRequiredDescription
organizationIdstring✅Identity Organization ID
publisherIdstring✅Marketplace publisher ID
verificationEnum<'unverified' | 'pending' | 'verified' | 'trusted' | 'partner'>✅Publisher verification status
agreementVersionstringoptionalAccepted developer agreement version
websitestringoptionalPublisher website
supportEmailstringoptionalPublisher support email
registeredAtstring✅

PublishingAnalyticsRequest

Properties

PropertyTypeRequiredDescription
listingIdstring✅Listing to get analytics for
timeRangeEnum<'last_7d' | 'last_30d' | 'last_90d' | 'last_365d' | 'all_time'>✅
metricsEnum<'installs' | 'uninstalls' | 'active_installs' | 'ratings' | 'revenue' | 'page_views'>[]optionalMetrics to include (default: all)

PublishingAnalyticsResponse

Properties

PropertyTypeRequiredDescription
listingIdstring✅
timeRangeEnum<'last_7d' | 'last_30d' | 'last_90d' | 'last_365d' | 'all_time'>✅
summaryObject✅
timeSeriesRecord<string, Object[]>optionalTime series keyed by metric name
ratingDistributionObjectoptional

ReleaseChannel

Allowed Values

  • alpha
  • beta
  • rc
  • stable

TimeSeriesPoint

Properties

PropertyTypeRequiredDescription
datestring✅
valuenumber✅

UpdateListingRequest

Properties

PropertyTypeRequiredDescription
listingIdstring✅Listing ID to update
namestringoptional
taglinestringoptional
descriptionstringoptional
categorystringoptional
tagsstring[]optional
iconUrlstringoptional
screenshotsObject[]optional
documentationUrlstringoptional
supportUrlstringoptional
repositoryUrlstringoptional
pricingEnum<'free' | 'freemium' | 'paid' | 'subscription' | 'usage-based' | 'contact-sales'>optional
priceInCentsintegeroptional

VersionRelease

Properties

PropertyTypeRequiredDescription
versionstring✅Semver version (e.g., 2.1.0-beta.1)
channelEnum<'alpha' | 'beta' | 'rc' | 'stable'>✅
releaseNotesstringoptionalRelease notes (Markdown)
changelogObject[]optionalStructured changelog entries
minPlatformVersionstringoptional
artifactUrlstringoptionalBuilt package artifact URL
artifactChecksumstringoptionalSHA-256 checksum
deprecatedboolean✅
deprecationMessagestringoptional
releasedAtstringoptional

On this page

Developer Portal ProtocolArchitecture AlignmentIdentity Integration (better-auth)Key ConceptsTypeScript UsageAnalyticsTimeRangeAllowed ValuesCreateListingRequestPropertiesListingActionRequestPropertiesPublisherProfilePropertiesPublishingAnalyticsRequestPropertiesPublishingAnalyticsResponsePropertiesReleaseChannelAllowed ValuesTimeSeriesPointPropertiesUpdateListingRequestPropertiesVersionReleaseProperties