App Store Protocol (Customer Experience)

Defines schemas for the end-customer experience when browsing, evaluating,

installing, and managing marketplace apps from within ObjectOS.

Architecture Alignment

Salesforce AppExchange (Customer): Browse apps, read reviews, 1-click install
Shopify App Store (Merchant): App evaluation, trial, install, manage subscriptions
Apple App Store (User): Ratings, reviews, featured collections, personalized recs

Customer Journey


Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage

Key Concepts

Reviews & Ratings: User-submitted ratings and reviews with moderation
Collections & Recommendations: Personalized discovery and curated picks
Subscription Management: Manage licenses, billing, and renewals
Installed App Management: Enable, disable, configure, upgrade, uninstall

Source: packages/spec/src/cloud/app-store.zod.ts

TypeScript Usage

import { AppDiscoveryRequest, AppDiscoveryResponse, AppSubscription, InstalledAppSummary, ListInstalledAppsRequest, ListInstalledAppsResponse, ListReviewsRequest, ListReviewsResponse, RecommendationReason, RecommendedApp, ReviewModerationStatus, SubmitReviewRequest, SubscriptionStatus, UserReview } from '@objectstack/spec/cloud';
import type { AppDiscoveryRequest, AppDiscoveryResponse, AppSubscription, InstalledAppSummary, ListInstalledAppsRequest, ListInstalledAppsResponse, ListReviewsRequest, ListReviewsResponse, RecommendationReason, RecommendedApp, ReviewModerationStatus, SubmitReviewRequest, SubscriptionStatus, UserReview } from '@objectstack/spec/cloud';

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

AppDiscoveryRequest

Properties

Property	Type	Required
tenantId	`string`	optional
categories	`Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>[]`	optional
platformVersion	`string`	optional
limit	`integer`	✅

AppDiscoveryResponse

Properties

Property	Type	Required
featured	`Object[]`	optional
recommended	`Object[]`	optional
trending	`Object[]`	optional
newArrivals	`Object[]`	optional
collections	`Object[]`	optional

AppSubscription

Properties

Property	Type	Required	Description
id	`string`	✅	Subscription ID
listingId	`string`	✅	App listing ID
tenantId	`string`	✅	Customer tenant ID
status	`Enum<'active' \| 'trialing' \| 'past-due' \| 'cancelled' \| 'expired'>`	✅
licenseKey	`string`	optional
plan	`string`	optional	Subscription plan name
billingCycle	`Enum<'monthly' \| 'annual'>`	optional
priceInCents	`integer`	optional
currentPeriodStart	`string`	optional
currentPeriodEnd	`string`	optional
trialEndDate	`string`	optional
autoRenew	`boolean`	✅
createdAt	`string`	✅

InstalledAppSummary

Properties

Property	Type	Required
listingId	`string`	✅
packageId	`string`	✅
name	`string`	✅
iconUrl	`string`	optional
installedVersion	`string`	✅
latestVersion	`string`	optional
updateAvailable	`boolean`	✅
enabled	`boolean`	✅
subscriptionStatus	`Enum<'active' \| 'trialing' \| 'past-due' \| 'cancelled' \| 'expired'>`	optional
installedAt	`string`	✅

ListInstalledAppsRequest

Properties

Property	Type	Required
tenantId	`string`	optional
enabled	`boolean`	optional
updateAvailable	`boolean`	optional
sortBy	`Enum<'name' \| 'installed-date' \| 'updated-date'>`	✅
page	`integer`	✅
pageSize	`integer`	✅

ListInstalledAppsResponse

Properties

Property	Type	Required
items	`Object[]`	✅
total	`integer`	✅
page	`integer`	✅
pageSize	`integer`	✅

ListReviewsRequest

Properties

Property	Type	Required	Description
listingId	`string`	✅	Listing to get reviews for
sortBy	`Enum<'newest' \| 'oldest' \| 'highest' \| 'lowest' \| 'most-helpful'>`	✅
rating	`integer`	optional
page	`integer`	✅
pageSize	`integer`	✅

ListReviewsResponse

Properties

Property	Type	Required
items	`Object[]`	✅
total	`integer`	✅
page	`integer`	✅
pageSize	`integer`	✅
ratingSummary	`Object`	optional

RecommendationReason

Allowed Values

popular-in-category
similar-users
complements-installed
trending
new-release
editor-pick

RecommendedApp

Properties

Property	Type	Required	Description
listingId	`string`	✅
name	`string`	✅
tagline	`string`	optional
iconUrl	`string`	optional
category	`Enum<'crm' \| 'erp' \| 'hr' \| 'finance' \| 'project' \| 'collaboration' \| 'analytics' \| 'integration' \| 'automation' \| 'ai' \| 'security' \| 'developer-tools' \| 'ui-theme' \| 'storage' \| 'other'>`	✅	Marketplace package category
pricing	`Enum<'free' \| 'freemium' \| 'paid' \| 'subscription' \| 'usage-based' \| 'contact-sales'>`	✅	Package pricing model
averageRating	`number`	optional
activeInstalls	`integer`	optional
reason	`Enum<'popular-in-category' \| 'similar-users' \| 'complements-installed' \| 'trending' \| 'new-release' \| 'editor-pick'>`	✅

ReviewModerationStatus

Allowed Values

pending
approved
flagged
rejected

SubmitReviewRequest

Properties

Property	Type	Required	Description
listingId	`string`	✅	Listing to review
rating	`integer`	✅	Star rating
title	`string`	optional
body	`string`	optional

SubscriptionStatus

Allowed Values

active
trialing
past-due
cancelled
expired

UserReview

Properties

Property	Type	Required	Description
id	`string`	✅	Review ID
listingId	`string`	✅	Listing being reviewed
userId	`string`	✅	Review author user ID
displayName	`string`	optional	Reviewer display name
rating	`integer`	✅	Star rating (1-5)
title	`string`	optional	Review title
body	`string`	optional	Review text
appVersion	`string`	optional	App version being reviewed
moderationStatus	`Enum<'pending' \| 'approved' \| 'flagged' \| 'rejected'>`	✅
helpfulCount	`integer`	✅
publisherResponse	`Object`	optional	Publisher response to review
submittedAt	`string`	✅
updatedAt	`string`	optional

App Store

On this page