@usehercules/sdk 1.4.0 → 1.6.0

package/src/client.ts

@@ -19,6 +19,12 @@ import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import { Beta } from './resources/beta/beta';
+import {
+  PushNotificationEnableResponse,
+  PushNotificationSendParams,
+  PushNotificationSendResponse,
+  PushNotifications,
+} from './resources/push-notifications/push-notifications';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -754,9 +760,11 @@ export class Hercules {
   static toFile = Uploads.toFile;
 
   beta: API.Beta = new API.Beta(this);
+  pushNotifications: API.PushNotifications = new API.PushNotifications(this);
 }
 
 Hercules.Beta = Beta;
+Hercules.PushNotifications = PushNotifications;
 
 export declare namespace Hercules {
   export type RequestOptions = Opts.RequestOptions;
@@ -765,4 +773,11 @@ export declare namespace Hercules {
   export { type CursorIDPageParams as CursorIDPageParams, type CursorIDPageResponse as CursorIDPageResponse };
 
   export { Beta as Beta };
+
+  export {
+    PushNotifications as PushNotifications,
+    type PushNotificationEnableResponse as PushNotificationEnableResponse,
+    type PushNotificationSendResponse as PushNotificationSendResponse,
+    type PushNotificationSendParams as PushNotificationSendParams,
+  };
 }

package/src/resources/index.ts

@@ -1,3 +1,9 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export { Beta } from './beta/beta';
+export {
+  PushNotifications,
+  type PushNotificationEnableResponse,
+  type PushNotificationSendResponse,
+  type PushNotificationSendParams,
+} from './push-notifications/push-notifications';

package/src/resources/push-notifications/index.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  PushNotifications,
+  type PushNotificationEnableResponse,
+  type PushNotificationSendResponse,
+  type PushNotificationSendParams,
+} from './push-notifications';
+export {
+  Subscriptions,
+  type SubscriptionCreateResponse,
+  type SubscriptionDeleteResponse,
+  type SubscriptionCreateParams,
+} from './subscriptions';
+export {
+  Topics,
+  type TopicListResponse,
+  type TopicSubscribeResponse,
+  type TopicUnsubscribeResponse,
+  type TopicListParams,
+  type TopicSubscribeParams,
+  type TopicUnsubscribeParams,
+} from './topics';

package/src/resources/push-notifications/push-notifications.ts

@@ -0,0 +1,141 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SubscriptionsAPI from './subscriptions';
+import {
+  SubscriptionCreateParams,
+  SubscriptionCreateResponse,
+  SubscriptionDeleteResponse,
+  Subscriptions,
+} from './subscriptions';
+import * as TopicsAPI from './topics';
+import {
+  TopicListParams,
+  TopicListResponse,
+  TopicSubscribeParams,
+  TopicSubscribeResponse,
+  TopicUnsubscribeParams,
+  TopicUnsubscribeResponse,
+  Topics,
+} from './topics';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+export class PushNotifications extends APIResource {
+  subscriptions: SubscriptionsAPI.Subscriptions = new SubscriptionsAPI.Subscriptions(this._client);
+  topics: TopicsAPI.Topics = new TopicsAPI.Topics(this._client);
+
+  /**
+   * Enables push notifications for the app by generating VAPID keys. Idempotent -
+   * returns existing keys if already enabled. Hercules recommends calling this
+   * during app initialization.
+   */
+  enable(options?: RequestOptions): APIPromise<PushNotificationEnableResponse> {
+    return this._client.post('/v1/push-notifications/enable', options);
+  }
+
+  /**
+   * Sends push notifications to specified visitors and/or topics. Specify
+   * visitorIds, topics, or both (combined as union). Omit both to broadcast to all
+   * subscribers.
+   */
+  send(body: PushNotificationSendParams, options?: RequestOptions): APIPromise<PushNotificationSendResponse> {
+    return this._client.post('/v1/push-notifications/send', { body, ...options });
+  }
+}
+
+/**
+ * Response containing the VAPID public key for push subscriptions.
+ */
+export interface PushNotificationEnableResponse {
+  /**
+   * VAPID public key for push subscription (base64url encoded)
+   */
+  vapidPublicKey: string;
+}
+
+/**
+ * Result of the send operation with success and failure counts.
+ */
+export interface PushNotificationSendResponse {
+  /**
+   * Number of notifications that failed to send
+   */
+  failed: number;
+
+  /**
+   * Number of notifications successfully sent
+   */
+  sent: number;
+}
+
+export interface PushNotificationSendParams {
+  /**
+   * Notification title
+   */
+  title: string;
+
+  /**
+   * Badge URL for mobile devices
+   */
+  badge?: string;
+
+  /**
+   * Notification body text
+   */
+  body?: string;
+
+  /**
+   * Custom data payload to include with the notification
+   */
+  data?: { [key: string]: unknown };
+
+  /**
+   * Icon URL (small icon displayed in the notification)
+   */
+  icon?: string;
+
+  /**
+   * Image URL (larger image displayed in the notification body)
+   */
+  image?: string;
+
+  /**
+   * Topics to send to. All visitors subscribed to any of these topics will receive
+   * the notification. Combined with visitorIds as a union.
+   */
+  topics?: Array<string>;
+
+  /**
+   * Visitor IDs to send to. Combined with topics as a union.
+   */
+  visitorIds?: Array<string>;
+}
+
+PushNotifications.Subscriptions = Subscriptions;
+PushNotifications.Topics = Topics;
+
+export declare namespace PushNotifications {
+  export {
+    type PushNotificationEnableResponse as PushNotificationEnableResponse,
+    type PushNotificationSendResponse as PushNotificationSendResponse,
+    type PushNotificationSendParams as PushNotificationSendParams,
+  };
+
+  export {
+    Subscriptions as Subscriptions,
+    type SubscriptionCreateResponse as SubscriptionCreateResponse,
+    type SubscriptionDeleteResponse as SubscriptionDeleteResponse,
+    type SubscriptionCreateParams as SubscriptionCreateParams,
+  };
+
+  export {
+    Topics as Topics,
+    type TopicListResponse as TopicListResponse,
+    type TopicSubscribeResponse as TopicSubscribeResponse,
+    type TopicUnsubscribeResponse as TopicUnsubscribeResponse,
+    type TopicListParams as TopicListParams,
+    type TopicSubscribeParams as TopicSubscribeParams,
+    type TopicUnsubscribeParams as TopicUnsubscribeParams,
+  };
+}

package/src/resources/push-notifications/subscriptions.ts

@@ -0,0 +1,96 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Subscriptions extends APIResource {
+  /**
+   * Registers a push subscription for a visitor. Upserts by endpoint to handle
+   * re-subscriptions gracefully.
+   */
+  create(body: SubscriptionCreateParams, options?: RequestOptions): APIPromise<SubscriptionCreateResponse> {
+    return this._client.post('/v1/push-notifications/subscriptions', { body, ...options });
+  }
+
+  /**
+   * Removes a push subscription by ID.
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<SubscriptionDeleteResponse> {
+    return this._client.delete(path`/v1/push-notifications/subscriptions/${id}`, options);
+  }
+}
+
+/**
+ * The created or updated subscription.
+ */
+export interface SubscriptionCreateResponse {
+  /**
+   * Subscription ID
+   */
+  id: string;
+}
+
+/**
+ * Result of the unsubscribe operation.
+ */
+export interface SubscriptionDeleteResponse {
+  /**
+   * Whether the subscription was removed
+   */
+  success: boolean;
+}
+
+export interface SubscriptionCreateParams {
+  /**
+   * Web Push subscription object from pushManager.subscribe()
+   */
+  subscription: SubscriptionCreateParams.Subscription;
+
+  /**
+   * Unique identifier for the subscriber (e.g., userId)
+   */
+  visitorId: string;
+}
+
+export namespace SubscriptionCreateParams {
+  /**
+   * Web Push subscription object from pushManager.subscribe()
+   */
+  export interface Subscription {
+    /**
+     * Push service endpoint URL
+     */
+    endpoint: string;
+
+    keys: Subscription.Keys;
+
+    /**
+     * Subscription expiration timestamp
+     */
+    expirationTime?: number | null;
+  }
+
+  export namespace Subscription {
+    export interface Keys {
+      /**
+       * Authentication secret (base64url encoded)
+       */
+      auth: string;
+
+      /**
+       * P-256 Diffie-Hellman public key (base64url encoded)
+       */
+      p256dh: string;
+    }
+  }
+}
+
+export declare namespace Subscriptions {
+  export {
+    type SubscriptionCreateResponse as SubscriptionCreateResponse,
+    type SubscriptionDeleteResponse as SubscriptionDeleteResponse,
+    type SubscriptionCreateParams as SubscriptionCreateParams,
+  };
+}

package/src/resources/push-notifications/topics.ts

@@ -0,0 +1,101 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Topics extends APIResource {
+  /**
+   * Lists all topics a visitor is subscribed to.
+   */
+  list(query: TopicListParams, options?: RequestOptions): APIPromise<TopicListResponse> {
+    return this._client.get('/v1/push-notifications/topics', { query, ...options });
+  }
+
+  /**
+   * Subscribes a visitor to topics. Topics are per-visitor, so all devices for this
+   * visitor will receive notifications sent to these topics.
+   */
+  subscribe(body: TopicSubscribeParams, options?: RequestOptions): APIPromise<TopicSubscribeResponse> {
+    return this._client.post('/v1/push-notifications/topics/subscribe', { body, ...options });
+  }
+
+  /**
+   * Unsubscribes a visitor from specified topics.
+   */
+  unsubscribe(body: TopicUnsubscribeParams, options?: RequestOptions): APIPromise<TopicUnsubscribeResponse> {
+    return this._client.post('/v1/push-notifications/topics/unsubscribe', { body, ...options });
+  }
+}
+
+/**
+ * List of topics the visitor is subscribed to.
+ */
+export interface TopicListResponse {
+  /**
+   * Topics the visitor is subscribed to
+   */
+  topics: Array<string>;
+}
+
+/**
+ * The visitor's updated topic subscriptions.
+ */
+export interface TopicSubscribeResponse {
+  /**
+   * Topics the visitor is now subscribed to
+   */
+  topics: Array<string>;
+}
+
+/**
+ * The visitor's remaining topic subscriptions after unsubscribing.
+ */
+export interface TopicUnsubscribeResponse {
+  /**
+   * Topics the visitor is still subscribed to
+   */
+  topics: Array<string>;
+}
+
+export interface TopicListParams {
+  /**
+   * Visitor ID to list topics for
+   */
+  visitorId: string;
+}
+
+export interface TopicSubscribeParams {
+  /**
+   * Topic names to subscribe to (e.g., 'announcements', 'channel:general')
+   */
+  topics: Array<string>;
+
+  /**
+   * Visitor ID to subscribe to topics
+   */
+  visitorId: string;
+}
+
+export interface TopicUnsubscribeParams {
+  /**
+   * Topic names to unsubscribe from
+   */
+  topics: Array<string>;
+
+  /**
+   * Visitor ID to unsubscribe from topics
+   */
+  visitorId: string;
+}
+
+export declare namespace Topics {
+  export {
+    type TopicListResponse as TopicListResponse,
+    type TopicSubscribeResponse as TopicSubscribeResponse,
+    type TopicUnsubscribeResponse as TopicUnsubscribeResponse,
+    type TopicListParams as TopicListParams,
+    type TopicSubscribeParams as TopicSubscribeParams,
+    type TopicUnsubscribeParams as TopicUnsubscribeParams,
+  };
+}

package/src/resources/push-notifications.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './push-notifications/index';

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '1.4.0'; // x-release-please-version
+export const VERSION = '1.6.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.6.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.6.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '1.4.0'; // x-release-please-version
+exports.VERSION = '1.6.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '1.4.0'; // x-release-please-version
+export const VERSION = '1.6.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map