Skip to main content

Publishing Applications to Seer Store

This document describes the flow for publishing applications to the Seer platform. Seer Store follows a specific implementation in the Seer Appstore codebase with a review-gated system to ensure quality and security of published applications.

Overview​

The Seer Store implementation follows these exact workflow steps:

  1. Projects are created and stored in the database
  2. Assets are stored in S3 bucket with URLs in the DB
  3. App packages (ZIPs) are stored in the database as bytea
  4. Reviewers can change app status through various stages
  5. Only apps with RELEASE status become available in the marketplace

Publishing Flow​

Sequence Diagram​

Simplified Flow​

From a developer's perspective, publishing an app involves:

  1. Setup: Register as a verified publisher and authenticate with a JWT token
  2. Upload: Submit your ZIP package via the POST endpoint with required metadata
  3. Review: Wait for approval as reviewers progress your app through status stages
  4. Publish: Once approved (RELEASE status), your app appears in the marketplace

Key Requirements and Constraints​

Based on analysis of the codebase, here are the key constraints and requirements for developers to publish packages:

1. Authentication Requirements​

  • JWT Token Required: Developers must have a valid JWT token using the "publisher" strategy
  • Bearer Token: Authentication is done via Authorization: Bearer <token> header
  • OAuth Options: The system supports multiple authentication methods:
    • GitHub OAuth (with github strategy)
    • Google OAuth (with google strategy)
    • Custom OAuth2 (with cusOAuth2Strategy)

2. Publisher Registration and Verification​

  • Publisher Account: Must have a registered publisher account with email
  • Verification Required: Publisher must be marked as verified: true in the database
  • Admin Verification: Unverified publishers get an error: "is not a verified publisher, please contact the Seer Administrator for more information"

3. Project Association​

  • Project Required: Must have a project already created that matches the app name and version
  • Ownership Check: Only the original publisher can publish updates to an app
  • Project Mapping: Apps must be associated with a project via appName and appVersion fields

4. Package Requirements​

  • ZIP Format Only: Only .zip files are accepted for package uploads
  • File Size Limit: 10MB maximum file size (limits: { fileSize: 10 * 1024 * 1024 })
  • Required Metadata: Must provide name, displayName, and version in the form data
  • Memory Storage: Files are stored in memory during upload using multer.memoryStorage()

5. Permission Levels​

  • Minimum Permission Level: Requires PermissionLevel.LV4 to upload applications
  • Status Management: Requires PermissionLevel.LV1 to change app status

6. Status Workflow​

  • Initial Status: New applications are created with SUBMISSION status by default
  • Available Statuses: SUBMISSION → REVIEW → APPROVAL → PRE_RELEASE → RELEASE → UNAVAILABLE
  • Release Requirement: Only apps with RELEASE status become available in the marketplace

7. Authentication Flow​

  1. Developer logs in via OAuth (GitHub/Google/OAuth2)
  2. System generates JWT token with publisher information
  3. Token includes email and permission level (default: LV4)
  4. Token expires in 1 year (expiresIn: "1y")

8. Publishing Endpoint​

  • URL: POST /publish/app or POST /publisher/app
  • Method: POST with multipart/form-data
  • Required Fields: file (ZIP), name, displayName, version
  • Optional Fields: description, category, semVer, etc.

9. Security Constraints​

  • Ownership Validation: System verifies that the publisher owns the project being updated
  • Environment Checks: In non-dev environments, strict ownership validation is enforced
  • Access Control: Publishers can only manage their own projects and apps

10. Technical Requirements​

  • Environment Variables: Requires proper configuration of JWT secret, AWS S3 credentials, OAuth provider settings
  • Database Connection: PostgreSQL database connection required
  • S3 Storage: AWS S3 bucket for asset storage (bucket name: "appstore-resources")

Developer Workflow​

When preparing to publish to the Seer Store, developers must follow these exact steps:

1. Setup and Authentication​

  • Register as a verified publisher account
  • Authenticate using OAuth (GitHub, Google, or custom OAuth2)
  • Obtain JWT token with publisher permissions
  • Ensure your permission level is at least LV4

2. Project Preparation​

  • Create a project in the database that matches your app name and version
  • Ensure you have the necessary project ownership
  • Prepare your application package as a ZIP file (max 10MB)

3. Package Upload​

  • Submit a POST request to /publish/app endpoint
  • Use multipart/form-data content type
  • Include the app ZIP file and required metadata (name, displayName, version)
  • Include the Authorization header with your JWT token

4. Review Process​

  • Application initially gets SUBMISSION status
  • Reviewers will progress the application through status stages
  • Wait for status to reach RELEASE to appear in marketplace
  • Only applications with RELEASE status are visible to end users

Best Practices​

  • Authentication: Ensure your JWT token is valid and has the required permission level
  • Verification: Confirm your publisher account is verified before attempting to publish
  • Project Association: Always have a matching project in the database before publishing
  • Package Quality: Keep ZIP files under 10MB and ensure all required metadata is provided
  • File Format: Only submit ZIP files as other formats are not accepted
  • Status Monitoring: Monitor your app's status throughout the review process
  • Security: Ensure your application meets security requirements and follows platform guidelines

Reference​

For more information about developing for Seer, refer to the API Documentation and Platform Features.