@skillrecordings/sdk 0.3.0 → 0.5.0

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * User entity returned by app integration.
  * Replaces Customer for consistency with SupportIntegration interface.
@@ -138,5 +140,355 @@ interface ContentSearchResponse {
         searchTimeMs?: number;
     };
 }
+/**
+ * Product type for availability checking.
+ * Self-paced is always available, live/cohort have limited seats.
+ */
+type ProductType = 'self-paced' | 'live' | 'cohort' | 'membership' | 'source-code-access' | (string & {});
+/**
+ * Product state lifecycle.
+ */
+type ProductState = 'draft' | 'active' | 'unavailable' | 'archived';
+/**
+ * Active promotion or sale for a product.
+ * Used by agent to answer presales questions about current discounts.
+ */
+interface Promotion {
+    id: string;
+    name: string;
+    /** Coupon code if applicable */
+    code?: string;
+    discountType: 'percent' | 'fixed';
+    /** Percentage (0-100) or fixed amount in cents */
+    discountAmount: number;
+    /** ISO date — when the promotion starts */
+    validFrom?: string;
+    /** ISO date — when the promotion ends */
+    validUntil?: string;
+    active: boolean;
+    /** Human-readable conditions (e.g., "PPP — purchasing power parity") */
+    conditions?: string;
+}
+/**
+ * Coupon/discount code details.
+ * Used by agent to validate coupon codes customers ask about.
+ */
+interface CouponInfo {
+    code: string;
+    valid: boolean;
+    discountType: 'percent' | 'fixed';
+    /** Percentage (0-100) or fixed amount in cents */
+    discountAmount: number;
+    /** Restriction category for the coupon */
+    restrictionType?: 'ppp' | 'student' | 'bulk' | 'general';
+    usageCount: number;
+    maxUses?: number;
+    /** ISO date — when the coupon expires */
+    expiresAt?: string;
+}
+/**
+ * App-specific refund policy configuration.
+ * Used by agent to give accurate refund window information
+ * instead of hardcoded defaults.
+ */
+interface RefundPolicy {
+    /** Days within which refunds are auto-approved */
+    autoApproveWindowDays: number;
+    /** Days within which refunds can be manually approved */
+    manualApproveWindowDays: number;
+    /** Days after which no refund is possible */
+    noRefundAfterDays?: number;
+    /** Special conditions (e.g., "Lifetime access: 60 day window") */
+    specialConditions?: string[];
+    /** URL to the full refund policy page */
+    policyUrl?: string;
+}
+/**
+ * Granular content access information for a user.
+ * Used by agent to debug access issues — goes beyond just "has a purchase".
+ */
+interface ContentAccess {
+    userId: string;
+    products: Array<{
+        productId: string;
+        productName: string;
+        accessLevel: 'full' | 'partial' | 'preview' | 'expired';
+        modules?: Array<{
+            id: string;
+            title: string;
+            accessible: boolean;
+        }>;
+        /** ISO date — when access expires (null = lifetime) */
+        expiresAt?: string;
+    }>;
+    /** Team membership info if user is part of a team */
+    teamMembership?: {
+        teamId: string;
+        teamName: string;
+        role: 'member' | 'admin' | 'owner';
+        /** ISO date — when the seat was claimed */
+        seatClaimedAt: string;
+    };
+}
+/**
+ * Recent user activity and progress data.
+ * Used by agent to debug access issues and assess product usage.
+ */
+interface UserActivity {
+    userId: string;
+    /** ISO date — last login timestamp */
+    lastLoginAt?: string;
+    /** ISO date — last meaningful activity */
+    lastActiveAt?: string;
+    lessonsCompleted: number;
+    totalLessons: number;
+    /** 0-100 completion percentage */
+    completionPercent: number;
+    recentItems: Array<{
+        type: 'lesson_completed' | 'exercise_submitted' | 'login' | 'download';
+        title: string;
+        /** ISO date */
+        timestamp: string;
+    }>;
+}
+/**
+ * Team license and seat management information.
+ * Used by agent to answer team/enterprise questions about seat allocation.
+ */
+interface LicenseInfo {
+    purchaseId: string;
+    licenseType: 'individual' | 'team' | 'enterprise' | 'site';
+    totalSeats: number;
+    claimedSeats: number;
+    availableSeats: number;
+    /** ISO date — when the license expires */
+    expiresAt?: string;
+    claimedBy: Array<{
+        email: string;
+        /** ISO date */
+        claimedAt: string;
+        /** ISO date */
+        lastActiveAt?: string;
+    }>;
+    /** Email of the license administrator */
+    adminEmail?: string;
+}
+/**
+ * App metadata for multi-app support.
+ * Eliminates hardcoded URLs and product names in agent prompts.
+ */
+interface AppInfo {
+    name: string;
+    instructorName: string;
+    supportEmail: string;
+    websiteUrl: string;
+    invoicesUrl?: string;
+    discordUrl?: string;
+    refundPolicyUrl?: string;
+    privacyPolicyUrl?: string;
+    termsUrl?: string;
+}
+/**
+ * Zod schema for ProductType validation
+ */
+declare const ProductTypeSchema: z.ZodUnion<readonly [z.ZodLiteral<"self-paced">, z.ZodLiteral<"live">, z.ZodLiteral<"cohort">, z.ZodLiteral<"membership">, z.ZodLiteral<"source-code-access">, z.ZodString]>;
+/**
+ * Zod schema for ProductState validation
+ */
+declare const ProductStateSchema: z.ZodEnum<{
+    active: "active";
+    draft: "draft";
+    unavailable: "unavailable";
+    archived: "archived";
+}>;
+/**
+ * Zod schema for ProductStatus validation
+ */
+declare const ProductStatusSchema: z.ZodObject<{
+    productId: z.ZodString;
+    productType: z.ZodUnion<readonly [z.ZodLiteral<"self-paced">, z.ZodLiteral<"live">, z.ZodLiteral<"cohort">, z.ZodLiteral<"membership">, z.ZodLiteral<"source-code-access">, z.ZodString]>;
+    available: z.ZodBoolean;
+    soldOut: z.ZodBoolean;
+    quantityAvailable: z.ZodNumber;
+    quantityRemaining: z.ZodNumber;
+    state: z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+        unavailable: "unavailable";
+        archived: "archived";
+    }>;
+    startsAt: z.ZodOptional<z.ZodString>;
+    endsAt: z.ZodOptional<z.ZodString>;
+    enrollmentOpen: z.ZodOptional<z.ZodString>;
+    enrollmentClose: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for Promotion validation
+ */
+declare const PromotionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    discountType: z.ZodEnum<{
+        percent: "percent";
+        fixed: "fixed";
+    }>;
+    discountAmount: z.ZodNumber;
+    validFrom: z.ZodOptional<z.ZodString>;
+    validUntil: z.ZodOptional<z.ZodString>;
+    active: z.ZodBoolean;
+    conditions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for CouponInfo validation
+ */
+declare const CouponInfoSchema: z.ZodObject<{
+    code: z.ZodString;
+    valid: z.ZodBoolean;
+    discountType: z.ZodEnum<{
+        percent: "percent";
+        fixed: "fixed";
+    }>;
+    discountAmount: z.ZodNumber;
+    restrictionType: z.ZodOptional<z.ZodEnum<{
+        ppp: "ppp";
+        student: "student";
+        bulk: "bulk";
+        general: "general";
+    }>>;
+    usageCount: z.ZodNumber;
+    maxUses: z.ZodOptional<z.ZodNumber>;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for RefundPolicy validation
+ */
+declare const RefundPolicySchema: z.ZodObject<{
+    autoApproveWindowDays: z.ZodNumber;
+    manualApproveWindowDays: z.ZodNumber;
+    noRefundAfterDays: z.ZodOptional<z.ZodNumber>;
+    specialConditions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    policyUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for ContentAccess validation
+ */
+declare const ContentAccessSchema: z.ZodObject<{
+    userId: z.ZodString;
+    products: z.ZodArray<z.ZodObject<{
+        productId: z.ZodString;
+        productName: z.ZodString;
+        accessLevel: z.ZodEnum<{
+            expired: "expired";
+            preview: "preview";
+            full: "full";
+            partial: "partial";
+        }>;
+        modules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            accessible: z.ZodBoolean;
+        }, z.core.$strip>>>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    teamMembership: z.ZodOptional<z.ZodObject<{
+        teamId: z.ZodString;
+        teamName: z.ZodString;
+        role: z.ZodEnum<{
+            member: "member";
+            admin: "admin";
+            owner: "owner";
+        }>;
+        seatClaimedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Zod schema for UserActivity validation
+ */
+declare const UserActivitySchema: z.ZodObject<{
+    userId: z.ZodString;
+    lastLoginAt: z.ZodOptional<z.ZodString>;
+    lastActiveAt: z.ZodOptional<z.ZodString>;
+    lessonsCompleted: z.ZodNumber;
+    totalLessons: z.ZodNumber;
+    completionPercent: z.ZodNumber;
+    recentItems: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            lesson_completed: "lesson_completed";
+            exercise_submitted: "exercise_submitted";
+            login: "login";
+            download: "download";
+        }>;
+        title: z.ZodString;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Zod schema for LicenseInfo validation
+ */
+declare const LicenseInfoSchema: z.ZodObject<{
+    purchaseId: z.ZodString;
+    licenseType: z.ZodEnum<{
+        individual: "individual";
+        team: "team";
+        enterprise: "enterprise";
+        site: "site";
+    }>;
+    totalSeats: z.ZodNumber;
+    claimedSeats: z.ZodNumber;
+    availableSeats: z.ZodNumber;
+    expiresAt: z.ZodOptional<z.ZodString>;
+    claimedBy: z.ZodArray<z.ZodObject<{
+        email: z.ZodString;
+        claimedAt: z.ZodString;
+        lastActiveAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    adminEmail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for AppInfo validation
+ */
+declare const AppInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    instructorName: z.ZodString;
+    supportEmail: z.ZodString;
+    websiteUrl: z.ZodString;
+    invoicesUrl: z.ZodOptional<z.ZodString>;
+    discordUrl: z.ZodOptional<z.ZodString>;
+    refundPolicyUrl: z.ZodOptional<z.ZodString>;
+    privacyPolicyUrl: z.ZodOptional<z.ZodString>;
+    termsUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Product availability/inventory status.
+ * Used by agent to accurately report whether products can be purchased.
+ *
+ * For live events/cohorts: check soldOut and quantityRemaining
+ * For self-paced: typically available=true, quantityAvailable=-1 (unlimited)
+ */
+interface ProductStatus {
+    /** Product identifier */
+    productId: string;
+    /** Type of product determines availability semantics */
+    productType: ProductType;
+    /** Whether the product can currently be purchased */
+    available: boolean;
+    /** Whether all seats/inventory are sold */
+    soldOut: boolean;
+    /** Total quantity available for sale (-1 = unlimited) */
+    quantityAvailable: number;
+    /** Remaining quantity not yet sold */
+    quantityRemaining: number;
+    /** Product lifecycle state */
+    state: ProductState;
+    /** For live events: when the event starts */
+    startsAt?: string;
+    /** For live events: when the event ends */
+    endsAt?: string;
+    /** For cohorts: when enrollment opens */
+    enrollmentOpen?: string;
+    /** For cohorts: when enrollment closes */
+    enrollmentClose?: string;
+}
 
-export type { ActionResult, ClaimedSeat, ContentSearchRequest, ContentSearchResponse, ContentSearchResult, Customer, Purchase, RefundRequest, RefundResult, Subscription, User };
+export { type ActionResult, type AppInfo, AppInfoSchema, type ClaimedSeat, type ContentAccess, ContentAccessSchema, type ContentSearchRequest, type ContentSearchResponse, type ContentSearchResult, type CouponInfo, CouponInfoSchema, type Customer, type LicenseInfo, LicenseInfoSchema, type ProductState, ProductStateSchema, type ProductStatus, ProductStatusSchema, type ProductType, ProductTypeSchema, type Promotion, PromotionSchema, type Purchase, type RefundPolicy, RefundPolicySchema, type RefundRequest, type RefundResult, type Subscription, type User, type UserActivity, UserActivitySchema };