@frontiertower/frontier-sdk 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -933,6 +933,514 @@ declare class PartnershipsAccess {
     }): Promise<void>;
 }
 
+/**
+ * Developer account information
+ */
+interface Developer {
+    /** Unique developer identifier */
+    id: number;
+    /** Developer name */
+    name: string;
+    /** Developer description */
+    description: string;
+    /** Developer email */
+    email: string;
+    /** API key */
+    apiKey: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Request payload for updating developer information
+ */
+interface UpdateDeveloperRequest {
+    /** Developer name */
+    name?: string;
+    /** Developer description */
+    description?: string;
+    /** Developer email */
+    email?: string;
+}
+/**
+ * Response from rotating an API key
+ */
+interface RotateKeyResponse {
+    /** Response message */
+    message: string;
+    /** Updated developer with new API key */
+    developer: Developer;
+}
+/**
+ * App status
+ */
+type AppStatus = 'in_review' | 'accepted' | 'released' | 'rejected' | 'request_deactivation' | 'deactivated';
+/**
+ * App permission type
+ */
+type AppPermission = string;
+/**
+ * Registered app information
+ */
+interface App {
+    /** Unique app identifier */
+    id: number;
+    /** Developer ID */
+    developer: number;
+    /** App icon URL */
+    icon: string | null;
+    /** App name */
+    name: string;
+    /** Human-readable app identifier */
+    readableId: string;
+    /** App description */
+    description: string;
+    /** App URL */
+    url: string;
+    /** CNAME entry for domain verification */
+    cnameEntry: string;
+    /** TXT entry for domain verification */
+    txtEntry: string | null;
+    /** App permissions */
+    permissions: AppPermission[];
+    /** Permission disclaimer text */
+    permissionDisclaimer: string;
+    /** App status */
+    status: AppStatus;
+    /** Review notes from admin */
+    reviewNotes: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Request payload for creating an app
+ */
+interface CreateAppRequest {
+    /** Developer ID */
+    developer: number;
+    /** App URL */
+    url: string;
+    /** CNAME entry for domain verification */
+    cnameEntry: string;
+    /** TXT entry for domain verification */
+    txtEntry?: string;
+    /** App permissions */
+    permissions: AppPermission[];
+    /** Permission disclaimer text */
+    permissionDisclaimer: string;
+}
+/**
+ * Request payload for updating an app
+ */
+interface UpdateAppRequest {
+    /** Developer ID */
+    developer?: number;
+    /** App URL */
+    url?: string;
+    /** CNAME entry for domain verification */
+    cnameEntry?: string;
+    /** TXT entry for domain verification */
+    txtEntry?: string;
+    /** App permissions */
+    permissions?: AppPermission[];
+    /** Permission disclaimer text */
+    permissionDisclaimer?: string;
+}
+/**
+ * Webhook status
+ */
+type WebhookStatus = 'IN_REVIEW' | 'LIVE' | 'REJECTED';
+/**
+ * Webhook event type
+ */
+type WebhookEvent = string;
+/**
+ * Webhook scope - maps event categories to specific IDs or '*' for all
+ */
+type WebhookScope = Record<string, number[] | '*'>;
+/**
+ * Webhook configuration
+ */
+interface WebhookConfig {
+    /** Event types subscribed to */
+    events: WebhookEvent[];
+    /** Scope of the webhook */
+    scope: WebhookScope;
+}
+/**
+ * Webhook information
+ */
+interface Webhook {
+    /** Unique webhook identifier */
+    id: number;
+    /** Developer ID */
+    developer: number;
+    /** Webhook name */
+    name: string;
+    /** Webhook description */
+    description: string;
+    /** Target URL for webhook delivery */
+    targetUrl: string;
+    /** Webhook configuration */
+    config: WebhookConfig;
+    /** Signing public key */
+    signingPublicKey: string;
+    /** Webhook status */
+    status: WebhookStatus;
+    /** Review notes from admin */
+    reviewNotes: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Request payload for creating a webhook
+ */
+interface CreateWebhookRequest {
+    /** Developer ID */
+    developer: number;
+    /** Webhook name */
+    name: string;
+    /** Webhook description */
+    description: string;
+    /** Target URL for webhook delivery */
+    targetUrl: string;
+    /** Webhook configuration */
+    config: WebhookConfig;
+}
+/**
+ * Request payload for updating a webhook
+ */
+interface UpdateWebhookRequest {
+    /** Developer ID */
+    developer?: number;
+    /** Webhook name */
+    name?: string;
+    /** Webhook description */
+    description?: string;
+    /** Target URL for webhook delivery */
+    targetUrl?: string;
+    /** Webhook configuration */
+    config?: WebhookConfig;
+}
+/**
+ * Response from rotating a webhook signing key
+ */
+interface RotateWebhookKeyResponse {
+    /** Response message */
+    message: string;
+    /** Updated webhook with new signing key */
+    webhook: Webhook;
+}
+/**
+ * Pagination parameters
+ */
+interface ListParams {
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset into the result set */
+    offset?: number;
+}
+/**
+ * Parameters for listing apps
+ */
+interface ListAppsParams extends ListParams {
+    /** Filter by developer ID */
+    developerId?: number;
+}
+/**
+ * Parameters for listing webhooks
+ */
+interface ListWebhooksParams extends ListParams {
+    /** Filter by developer ID */
+    developerId?: number;
+}
+/**
+ * Third-party access class for interacting with third-party developer features.
+ *
+ * This class provides methods to:
+ * - Manage developer accounts
+ * - Register and manage apps
+ * - Configure webhooks for event notifications
+ *
+ * All methods require appropriate permissions and authentication.
+ */
+declare class ThirdPartyAccess {
+    private sdk;
+    constructor(sdk: FrontierSDK);
+    /**
+     * List developer accounts (paginated)
+     * Requires permission: `thirdParty:listDevelopers` or `thirdParty:*`
+     *
+     * @param payload.limit - Maximum number of results to return
+     * @param payload.offset - Offset into the result set
+     * @returns Paginated response of developers
+     *
+     * @example
+     * ```typescript
+     * const developers = await sdk.getThirdParty().listDevelopers({ limit: 20, offset: 0 });
+     * console.log('Total developers:', developers.count);
+     * ```
+     */
+    listDevelopers(payload?: ListParams): Promise<PaginatedResponse<Developer>>;
+    /**
+     * Get developer details by ID
+     * Requires permission: `thirdParty:getDeveloper` or `thirdParty:*`
+     *
+     * @param payload.id - Developer ID
+     * @returns Developer details
+     *
+     * @example
+     * ```typescript
+     * const developer = await sdk.getThirdParty().getDeveloper({ id: 123 });
+     * console.log('Developer:', developer.name);
+     * ```
+     */
+    getDeveloper(payload: {
+        id: number;
+    }): Promise<Developer>;
+    /**
+     * Update developer information
+     * Requires permission: `thirdParty:updateDeveloper` or `thirdParty:*`
+     *
+     * @param payload.id - Developer ID
+     * @param payload.data - Update data
+     * @returns Updated developer
+     *
+     * @example
+     * ```typescript
+     * const developer = await sdk.getThirdParty().updateDeveloper({
+     *   id: 123,
+     *   data: { name: 'New Name', website: 'https://example.com' }
+     * });
+     * ```
+     */
+    updateDeveloper(payload: {
+        id: number;
+        data: UpdateDeveloperRequest;
+    }): Promise<Developer>;
+    /**
+     * Rotate developer API key
+     * Requires permission: `thirdParty:rotateDeveloperApiKey` or `thirdParty:*`
+     *
+     * Note: The new API key is only shown once in the response
+     *
+     * @param payload.id - Developer ID
+     * @returns Response containing the new API key
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getThirdParty().rotateDeveloperApiKey({ id: 123 });
+     * console.log('New API key:', result.apiKey);
+     * // Store this key securely - it won't be shown again!
+     * ```
+     */
+    rotateDeveloperApiKey(payload: {
+        id: number;
+    }): Promise<RotateKeyResponse>;
+    /**
+     * List registered apps (paginated)
+     * Requires permission: `thirdParty:listApps` or `thirdParty:*`
+     *
+     * @param payload.limit - Maximum number of results to return
+     * @param payload.offset - Offset into the result set
+     * @param payload.developerId - Filter by developer ID
+     * @returns Paginated response of apps
+     *
+     * @example
+     * ```typescript
+     * const apps = await sdk.getThirdParty().listApps({ limit: 20, offset: 0 });
+     * console.log('Total apps:', apps.count);
+     *
+     * // Filter by developer
+     * const devApps = await sdk.getThirdParty().listApps({ developerId: 123 });
+     * ```
+     */
+    listApps(payload?: ListAppsParams): Promise<PaginatedResponse<App>>;
+    /**
+     * Register a new app
+     * Requires permission: `thirdParty:createApp` or `thirdParty:*`
+     *
+     * Note: App name, description, and icon are automatically fetched from the URL's metadata
+     *
+     * @param payload - App creation payload with URL
+     * @returns Created app
+     *
+     * @example
+     * ```typescript
+     * const app = await sdk.getThirdParty().createApp({
+     *   url: 'https://myapp.example.com'
+     * });
+     * console.log('Created app:', app.id, app.name);
+     * ```
+     */
+    createApp(payload: CreateAppRequest): Promise<App>;
+    /**
+     * Get app details by ID
+     * Requires permission: `thirdParty:getApp` or `thirdParty:*`
+     *
+     * @param payload.id - App ID
+     * @returns App details
+     *
+     * @example
+     * ```typescript
+     * const app = await sdk.getThirdParty().getApp({ id: 123 });
+     * console.log('App:', app.name, app.status);
+     * ```
+     */
+    getApp(payload: {
+        id: number;
+    }): Promise<App>;
+    /**
+     * Update an app
+     * Requires permission: `thirdParty:updateApp` or `thirdParty:*`
+     *
+     * @param payload.id - App ID
+     * @param payload.data - Update data
+     * @returns Updated app
+     *
+     * @example
+     * ```typescript
+     * const app = await sdk.getThirdParty().updateApp({
+     *   id: 123,
+     *   data: { name: 'Updated App Name', description: 'New description' }
+     * });
+     * ```
+     */
+    updateApp(payload: {
+        id: number;
+        data: UpdateAppRequest;
+    }): Promise<App>;
+    /**
+     * Request app deactivation
+     * Requires permission: `thirdParty:deleteApp` or `thirdParty:*`
+     *
+     * @param payload.id - App ID
+     *
+     * @example
+     * ```typescript
+     * await sdk.getThirdParty().deleteApp({ id: 123 });
+     * ```
+     */
+    deleteApp(payload: {
+        id: number;
+    }): Promise<void>;
+    /**
+     * List webhooks (paginated)
+     * Requires permission: `thirdParty:listWebhooks` or `thirdParty:*`
+     *
+     * Note: Maximum 3 webhooks per developer account
+     *
+     * @param payload.limit - Maximum number of results to return
+     * @param payload.offset - Offset into the result set
+     * @param payload.developerId - Filter by developer ID
+     * @returns Paginated response of webhooks
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await sdk.getThirdParty().listWebhooks({ limit: 10, offset: 0 });
+     * console.log('Total webhooks:', webhooks.count);
+     *
+     * // Filter by developer
+     * const devWebhooks = await sdk.getThirdParty().listWebhooks({ developerId: 123 });
+     * ```
+     */
+    listWebhooks(payload?: ListWebhooksParams): Promise<PaginatedResponse<Webhook>>;
+    /**
+     * Create a new webhook
+     * Requires permission: `thirdParty:createWebhook` or `thirdParty:*`
+     *
+     * Note: New webhooks require admin approval before going live
+     *
+     * @param payload - Webhook creation payload
+     * @returns Created webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sdk.getThirdParty().createWebhook({
+     *   url: 'https://myapp.example.com/webhooks',
+     *   events: ['app.approved', 'user.registered']
+     * });
+     * console.log('Created webhook:', webhook.id);
+     * ```
+     */
+    createWebhook(payload: CreateWebhookRequest): Promise<Webhook>;
+    /**
+     * Get webhook details by ID
+     * Requires permission: `thirdParty:getWebhook` or `thirdParty:*`
+     *
+     * @param payload.id - Webhook ID
+     * @returns Webhook details
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sdk.getThirdParty().getWebhook({ id: 123 });
+     * console.log('Webhook:', webhook.url, webhook.status);
+     * ```
+     */
+    getWebhook(payload: {
+        id: number;
+    }): Promise<Webhook>;
+    /**
+     * Update a webhook
+     * Requires permission: `thirdParty:updateWebhook` or `thirdParty:*`
+     *
+     * Note: Config changes require admin approval before going live
+     *
+     * @param payload.id - Webhook ID
+     * @param payload.data - Update data
+     * @returns Updated webhook
+     *
+     * @example
+     * ```typescript
+     * const webhook = await sdk.getThirdParty().updateWebhook({
+     *   id: 123,
+     *   data: { url: 'https://newurl.example.com/webhooks' }
+     * });
+     * ```
+     */
+    updateWebhook(payload: {
+        id: number;
+        data: UpdateWebhookRequest;
+    }): Promise<Webhook>;
+    /**
+     * Delete a webhook
+     * Requires permission: `thirdParty:deleteWebhook` or `thirdParty:*`
+     *
+     * @param payload.id - Webhook ID
+     *
+     * @example
+     * ```typescript
+     * await sdk.getThirdParty().deleteWebhook({ id: 123 });
+     * ```
+     */
+    deleteWebhook(payload: {
+        id: number;
+    }): Promise<void>;
+    /**
+     * Rotate webhook signing key
+     * Requires permission: `thirdParty:rotateWebhookSigningKey` or `thirdParty:*`
+     *
+     * Note: The new signing public key is returned in the response
+     *
+     * @param payload.id - Webhook ID
+     * @returns Response containing the new signing public key
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getThirdParty().rotateWebhookSigningKey({ id: 123 });
+     * console.log('New signing key:', result.signingPublicKey);
+     * ```
+     */
+    rotateWebhookSigningKey(payload: {
+        id: number;
+    }): Promise<RotateWebhookKeyResponse>;
+}
+
 declare class FrontierSDK {
     private requestId;
     private pendingRequests;
@@ -941,6 +1449,7 @@ declare class FrontierSDK {
     private chain;
     private user;
     private partnerships;
+    private thirdParty;
     constructor();
     private handleMessage;
     /**
@@ -969,6 +1478,10 @@ declare class FrontierSDK {
      * Get partnerships access instance
      */
     getPartnerships(): PartnershipsAccess;
+    /**
+     * Get third-party access instance
+     */
+    getThirdParty(): ThirdPartyAccess;
     /**
      * Cleanup: Remove event listeners
      * Call this when your app is being destroyed
@@ -988,4 +1501,4 @@ interface SDKResponse {
     error?: string;
 }
 
-export { ChainAccess, type ChainConfig, type CreateSponsorPassRequest, type ExecuteCall, FrontierSDK, type GasOverrides, type ListSponsorsParams, type PaginatedResponse, PartnershipsAccess, type ReferralDetails, type ReferralOverview, type SDKRequest, type SDKResponse, type SmartAccount, type Sponsor, type SponsorPass, StorageAccess, type SwapParams, type SwapQuote, type SwapResult, SwapResultStatus, type User, UserAccess, type UserContact, type UserContactPayload, type UserOperationReceipt, type UserProfile, WalletAccess };
+export { type App, type AppPermission, type AppStatus, ChainAccess, type ChainConfig, type CreateAppRequest, type CreateSponsorPassRequest, type CreateWebhookRequest, type Developer, type ExecuteCall, FrontierSDK, type GasOverrides, type ListParams, type ListSponsorsParams, type PaginatedResponse, PartnershipsAccess, type ReferralDetails, type ReferralOverview, type RotateKeyResponse, type RotateWebhookKeyResponse, type SDKRequest, type SDKResponse, type SmartAccount, type Sponsor, type SponsorPass, StorageAccess, type SwapParams, type SwapQuote, type SwapResult, SwapResultStatus, ThirdPartyAccess, type UpdateAppRequest, type UpdateDeveloperRequest, type UpdateWebhookRequest, type User, UserAccess, type UserContact, type UserContactPayload, type UserOperationReceipt, type UserProfile, WalletAccess, type Webhook, type WebhookConfig, type WebhookEvent, type WebhookScope, type WebhookStatus };