API Shared Package

TypeScript client library for Upbound's backend APIs with type-safe annotation support.

Features

• Type-safe API clients with Zod schema validation
• Shimmer v2 search with rich annotation metadata
• Comprehensive annotation types for packages and resources
• Full TypeScript support with exported types

Basic Usage

import { ShimmerV2 } from '@upbound/api';

const shimmer = new ShimmerV2({ get: fetch });

// Search packages with annotation data
const packages = await shimmer.searchPackages({
  query: 'provider-aws',
  tier: 'official',
});

// Access annotation metadata
packages.packages.forEach(pkg => {
  if (pkg.annotations) {
    console.log('Hardening:', pkg.annotations.hardening); // ['FIPS', 'CVE Remediation']
    console.log('Host compatibility:', pkg.annotations.host); // ['UXP', 'Spaces']
    console.log('License:', pkg.annotations.license); // ['Apache-2.0']
    console.log('Subscription:', pkg.annotations.subscription); // ['Enterprise']
  }
});

Annotation Types

| Field | Values | Description | | -------------- | -------------------------------------------------------------- | --------------------------- | | hardening | ['Backporting', 'CVE Remediation', 'FIPS'] | Security hardening measures | | host | ['XP', 'UXP', 'Spaces'] | Platform compatibility | | license | SPDX identifiers | License information | | subscription | ['Community', 'Standard', 'Enterprise', 'Business Critical'] | Required subscription tier | | support | ['Upbound', 'Partner'] | Support providers | | verification | ['Official', 'Partner'] | Verification status |

Type Exports

import type {
  // Annotation schemas & types
  HardeningAnnotation,
  HostAnnotation,
  SubscriptionAnnotation,
  SupportAnnotation,
  VerificationAnnotation,
  LicenseAnnotation,
  Annotations,

  // Search payload and result types
  SearchPayload,
  PackageSearchResults,
  PackageSearchResult,
  ResourceSearchResults,
  ResourceSearchResult,
  CommonSearchResult,
} from '@upbound/api';

Error Handling

try {
  const result = await shimmer.searchPackages({ query: 'test' });
  console.log(result.packages[0].annotations?.hardening);
} catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation error:', error.errors);
  } else {
    console.error('API error:', error);
  }
}

Backward Compatibility

All annotation fields are optional - existing code continues to work unchanged. Annotations are only present when provided by the API.