perspectapi-ts-sdk 3.7.0 → 5.0.0

package/src/v2/types.ts

@@ -0,0 +1,395 @@
+/**
+ * v2 SDK Types — matches the API wire format exactly (snake_case).
+ *
+ * These types reflect the actual JSON returned by /api/v2/ endpoints.
+ * No transformation layer is needed in the SDK.
+ */
+
+// --- Base types ---
+
+export interface V2Object {
+  object: string;
+  id: string;
+}
+
+export interface V2List<T> {
+  object: "list";
+  data: T[];
+  has_more: boolean;
+  url: string;
+}
+
+export interface V2Deleted {
+  object: string;
+  id: string;
+  deleted: true;
+}
+
+export interface V2Error {
+  error: {
+    type: V2ErrorType;
+    code: string;
+    message: string;
+    param?: string;
+  };
+}
+
+export type V2ErrorType =
+  | "invalid_request_error"
+  | "authentication_error"
+  | "permission_error"
+  | "not_found_error"
+  | "rate_limit_error"
+  | "api_error";
+
+// --- Pagination ---
+
+export interface V2PaginationParams {
+  limit?: number;
+  starting_after?: string;
+  ending_before?: string;
+}
+
+// --- Content ---
+
+export interface V2Content extends V2Object {
+  object: "content";
+  title: string;
+  content: string;
+  markdown: string | null;
+  slug: string;
+  slug_prefix: string | null;
+  type: "post" | "page" | "block";
+  status: "draft" | "publish" | "private" | "trash" | "scheduled";
+  author: string | null;
+  custom: Record<string, unknown> | null;
+  featured_image?: string | null;
+  scheduled_at: string | null;
+  published_at: string;
+  updated_at: string;
+}
+
+export interface V2ContentCreateParams {
+  title: string;
+  content: string;
+  markdown?: string;
+  custom?: Record<string, unknown>;
+  slug?: string;
+  slug_prefix?: string;
+  published_at?: string;
+  scheduled_at?: string | null;
+  status?: "draft" | "publish" | "private" | "trash" | "scheduled";
+  type?: "post" | "page" | "block";
+}
+
+export interface V2ContentUpdateParams extends Partial<V2ContentCreateParams> {}
+
+export interface V2ContentListParams extends V2PaginationParams {
+  status?: "draft" | "publish" | "private" | "trash" | "scheduled";
+  type?: "post" | "page" | "block";
+  search?: string;
+  slug_prefix?: string;
+}
+
+// --- Products ---
+
+export interface V2Product extends V2Object {
+  object: "product";
+  name: string;
+  description: string | null;
+  excerpt: string | null;
+  meta_description: string | null;
+  price: number;
+  unit_amount: number;
+  currency: string;
+  sku: string | null;
+  slug: string | null;
+  slug_prefix: string | null;
+  published: boolean;
+  stock_quantity: number | null;
+  custom: Record<string, unknown> | null;
+  recurring: { interval: string; interval_count?: number } | null;
+  tax_behavior: "inclusive" | "exclusive" | "unspecified" | null;
+  category_id: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2ProductCreateParams {
+  name: string;
+  description?: string;
+  excerpt?: string;
+  meta_description?: string;
+  category_id?: string;
+  price: number;
+  unit_amount: number;
+  currency?: string;
+  sku?: string;
+  custom?: Record<string, unknown>;
+  slug?: string;
+  slug_prefix?: string;
+  published?: boolean;
+  stock_quantity?: number | null;
+  recurring?: { interval: "day" | "week" | "month" | "year"; interval_count?: number };
+  tax_behavior?: "inclusive" | "exclusive" | "unspecified";
+  attachment_ids?: number[];
+}
+
+export interface V2ProductUpdateParams extends Partial<V2ProductCreateParams> {}
+
+export interface V2ProductListParams extends V2PaginationParams {
+  published?: boolean;
+  category_id?: string;
+  search?: string;
+  slug_prefix?: string;
+}
+
+// --- Categories ---
+
+export interface V2Category extends V2Object {
+  object: "category";
+  name: string;
+  description: string | null;
+  slug: string | null;
+  slug_prefix: string | null;
+  parent_id: string | null;
+  type: "post" | "product" | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2CategoryCreateParams {
+  name: string;
+  description?: string;
+  slug?: string;
+  slug_prefix?: string;
+  parent_id?: string;
+  type?: "post" | "product";
+}
+
+export interface V2CategoryUpdateParams extends Partial<V2CategoryCreateParams> {}
+
+// --- Collections ---
+
+export interface V2Collection extends V2Object {
+  object: "collection";
+  name: string;
+  description: string | null;
+  available_from: string | null;
+  available_until: string | null;
+  published: boolean;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2CollectionItem extends V2Object {
+  object: "collection_item";
+  collection_id: string;
+  product_id: string;
+  max_quantity: number | null;
+  position: number;
+}
+
+export interface V2CollectionCreateParams {
+  name: string;
+  description?: string | null;
+  available_from?: string | null;
+  available_until?: string | null;
+  published?: boolean;
+}
+
+export interface V2CollectionUpdateParams extends Partial<V2CollectionCreateParams> {}
+
+// --- Orders (Checkout Sessions) ---
+
+export interface V2Order extends V2Object {
+  object: "checkout_session";
+  customer_email: string;
+  customer_name: string | null;
+  customer_phone: string | null;
+  customer_details: Record<string, unknown> | null;
+  shipping_details: Record<string, unknown> | null;
+  order_id: string | null;
+  line_items: unknown[] | null;
+  amount_total: number;
+  currency: string;
+  tax_summary: Record<string, unknown> | null;
+  status: string;
+  payment_status: string | null;
+  fulfillment_status: string | null;
+  tracking_number: string | null;
+  notes: string | null;
+  live_mode: boolean;
+  metadata: Record<string, unknown> | null;
+  created_at: string;
+  completed_at: string | null;
+  expires_at: string | null;
+}
+
+export interface V2OrderListParams extends V2PaginationParams {
+  status?: string;
+  customer_email?: string;
+  date_from?: string;
+  date_to?: string;
+}
+
+// --- Site Users ---
+
+export interface V2SiteUser extends V2Object {
+  object: "site_user";
+  email: string;
+  email_verified: boolean;
+  first_name: string | null;
+  last_name: string | null;
+  avatar_url: string | null;
+  status: string;
+  waitlist: boolean;
+  metadata: Record<string, unknown> | null;
+  created_at: string | null;
+  updated_at: string | null;
+  last_login_at: string | null;
+}
+
+export interface V2SiteUserUpdateParams {
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  status?: "active" | "suspended" | "pending_verification";
+  metadata?: Record<string, unknown>;
+}
+
+export interface V2SiteUserListParams extends V2PaginationParams {
+  status?: "active" | "suspended" | "pending_verification";
+  email?: string;
+}
+
+// --- Newsletter ---
+
+export interface V2NewsletterSubscription extends V2Object {
+  object: "newsletter_subscription";
+  email: string;
+  name: string | null;
+  status: string;
+  double_opt_in: boolean;
+  confirmed_at: string | null;
+  source: string | null;
+  frequency: string | null;
+  topics: string[] | null;
+  language: string | null;
+  tags: string[] | null;
+  custom_fields: Record<string, unknown> | null;
+  unsubscribed_at: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2NewsletterList extends V2Object {
+  object: "newsletter_list";
+  name: string;
+  slug: string;
+  description: string | null;
+  is_default: boolean;
+  subscriber_count: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2NewsletterCampaign extends V2Object {
+  object: "newsletter_campaign";
+  name: string;
+  slug: string | null;
+  subject: string;
+  preview_text: string | null;
+  status: string;
+  sent_at: string | null;
+  completed_at: string | null;
+  total_recipients: number;
+  sent_count: number;
+  opened_count: number;
+  clicked_count: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Contact ---
+
+export interface V2ContactSubmission extends V2Object {
+  object: "contact_submission";
+  name: string | null;
+  first_name: string | null;
+  last_name: string | null;
+  email: string;
+  subject: string | null;
+  message: string;
+  phone: string | null;
+  company: string | null;
+  status: string;
+  metadata: Record<string, unknown> | null;
+  created_at: string | null;
+  processed_at: string | null;
+}
+
+// --- Organizations ---
+
+export interface V2Organization extends V2Object {
+  object: "organization";
+  name: string;
+  slug: string | null;
+  endpoint_status: string | null;
+  endpoint_url: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Sites ---
+
+export interface V2Site extends V2Object {
+  object: "site";
+  name: string;
+  title: string | null;
+  description: string | null;
+  domain: string | null;
+  custom_domain: string | null;
+  organization_id: string | null;
+  tax_enabled: boolean;
+  lifecycle_status: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- API Keys ---
+
+export interface V2ApiKey extends V2Object {
+  object: "api_key";
+  name: string;
+  description: string | null;
+  organization_id: string | null;
+  site_name: string | null;
+  permissions: string[] | null;
+  is_active: boolean;
+  expires_at: string | null;
+  last_used_at: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Webhooks ---
+
+export interface V2Webhook extends V2Object {
+  object: "webhook";
+  url: string;
+  description: string | null;
+  events: string[] | null;
+  is_active: boolean;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2WebhookCreateParams {
+  url: string;
+  description?: string;
+  events?: string[];
+  is_active?: boolean;
+}
+
+export interface V2WebhookUpdateParams extends Partial<V2WebhookCreateParams> {}