@pushflodev/sdk 1.0.3 → 1.0.4

package/README.md

@@ -409,6 +409,67 @@ client.on('error', (error) => {
 | `ConnectionError` | WebSocket connection issues | Yes |
 | `AuthenticationError` | Invalid/missing API key | No |
 | `NetworkError` | HTTP request failures | Varies |
+| `ValidationError` | Invalid input (e.g., channel slug) | No |
+
+## Channel Naming Rules
+
+Channel slugs must follow these rules:
+
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Lowercase only | `my-channel` | `My-Channel` |
+| Letters, numbers, hyphens | `channel-123` | `channel:123` |
+| No special characters | `my-channel` | `my_channel`, `my.channel` |
+| No leading/trailing hyphens | `my-channel` | `-channel`, `channel-` |
+| No consecutive hyphens | `my-channel` | `my--channel` |
+| 1-64 characters | `a` to 64 chars | empty or >64 chars |
+
+### Validation Utilities
+
+```typescript
+import {
+  isValidChannelSlug,
+  toChannelSlug,
+  validateChannelSlug,
+} from '@pushflodev/sdk';
+
+// Check if valid
+isValidChannelSlug('my-channel');     // true
+isValidChannelSlug('my:channel');     // false
+
+// Convert to valid slug
+toChannelSlug('My Channel!');         // 'my-channel'
+toChannelSlug('user:123:messages');   // 'user-123-messages'
+
+// Detailed validation with suggestions
+const result = validateChannelSlug('My:Channel');
+// {
+//   valid: false,
+//   error: "Channel slug contains invalid characters: :. Only lowercase letters, numbers, and hyphens are allowed.",
+//   suggestion: "my-channel"
+// }
+```
+
+### Auto-Creating Channels
+
+If you need to auto-create channels with dynamic names, use `toChannelSlug()` to ensure valid slugs:
+
+```typescript
+import { PushFloServer, toChannelSlug } from '@pushflodev/sdk/server';
+
+const server = new PushFloServer({ secretKey: 'sec_xxx' });
+
+// Convert dynamic names to valid slugs
+const orgId = 'org_abc123';
+const brandId = 'brand_xyz789';
+const channelSlug = toChannelSlug(`${orgId}-${brandId}-notifications`);
+// Result: 'org-abc123-brand-xyz789-notifications'
+
+await server.createChannel({
+  name: 'Brand Notifications',
+  slug: channelSlug,
+});
+```
 
 ## Environment Variables
 

package/dist/{PushFloClient-ny0iyTYJ.d.ts → PushFloClient-B4smuFOa.d.ts}

@@ -77,6 +77,8 @@ declare class PushFloClient extends TypedEventEmitter<PushFloClientEvents> {
     destroy(): void;
     /**
      * Subscribe to a channel
+     *
+     * @throws {ValidationError} If the channel slug is invalid
      */
     subscribe(channel: string, options?: SubscriptionOptions): Subscription;
     /**

package/dist/{PushFloClient-JPowShqE.d.cts → PushFloClient-DqOYR0GV.d.cts}

@@ -77,6 +77,8 @@ declare class PushFloClient extends TypedEventEmitter<PushFloClientEvents> {
     destroy(): void;
     /**
      * Subscribe to a channel
+     *
+     * @throws {ValidationError} If the channel slug is invalid
      */
     subscribe(channel: string, options?: SubscriptionOptions): Subscription;
     /**

package/dist/{api-DYrG_5uC.d.cts → api-Dgp2k2ZF.d.cts}

@@ -71,6 +71,86 @@ declare class NetworkError extends PushFloError {
     toJSON(): Record<string, unknown>;
 }
 
+/**
+ * Error thrown when input validation fails
+ */
+declare class ValidationError extends PushFloError {
+    /** The field that failed validation */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+    /**
+     * Create an error for an invalid channel slug
+     */
+    static invalidChannelSlug(slug: string): ValidationError;
+    /**
+     * Create an error for a required field
+     */
+    static required(field: string): ValidationError;
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Channel slug validation utilities
+ *
+ * Channel slugs must follow these rules:
+ * - 1-64 characters long
+ * - Lowercase letters (a-z), numbers (0-9), and hyphens (-) only
+ * - Cannot start or end with a hyphen
+ * - Cannot have consecutive hyphens
+ */
+/** Maximum length for a channel slug */
+declare const MAX_SLUG_LENGTH = 64;
+/** Minimum length for a channel slug */
+declare const MIN_SLUG_LENGTH = 1;
+/**
+ * Check if a channel slug is valid
+ *
+ * @param slug - The channel slug to validate
+ * @returns true if the slug is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidChannelSlug('my-channel')     // true
+ * isValidChannelSlug('channel-123')    // true
+ * isValidChannelSlug('a')              // true
+ * isValidChannelSlug('My-Channel')     // false (uppercase)
+ * isValidChannelSlug('-channel')       // false (starts with hyphen)
+ * isValidChannelSlug('channel:name')   // false (contains colon)
+ * isValidChannelSlug('channel_name')   // false (contains underscore)
+ * ```
+ */
+declare function isValidChannelSlug(slug: string): boolean;
+/**
+ * Convert a string to a valid channel slug
+ *
+ * @param str - The string to convert
+ * @returns A valid channel slug
+ *
+ * @example
+ * ```typescript
+ * toChannelSlug('My Channel')           // 'my-channel'
+ * toChannelSlug('Hello World!')         // 'hello-world'
+ * toChannelSlug('user:123:messages')    // 'user-123-messages'
+ * toChannelSlug('___test___')           // 'test'
+ * ```
+ */
+declare function toChannelSlug(str: string): string;
+/**
+ * Validation result with detailed error information
+ */
+interface SlugValidationResult {
+    valid: boolean;
+    error?: string;
+    suggestion?: string;
+}
+/**
+ * Validate a channel slug with detailed error messages
+ *
+ * @param slug - The channel slug to validate
+ * @returns Validation result with error details and suggestions
+ */
+declare function validateChannelSlug(slug: string): SlugValidationResult;
+
 /**
  * A PushFlo channel
  */
@@ -146,4 +226,4 @@ interface Pagination {
     totalPages: number;
 }
 
-export { AuthenticationError as A, type Channel as C, type ListChannelsOptions as L, NetworkError as N, PushFloError as P, type ChannelInput as a, type ChannelUpdateInput as b, type Pagination as c };
+export { AuthenticationError as A, type Channel as C, type ListChannelsOptions as L, MAX_SLUG_LENGTH as M, NetworkError as N, PushFloError as P, type SlugValidationResult as S, ValidationError as V, type ChannelInput as a, type ChannelUpdateInput as b, MIN_SLUG_LENGTH as c, type Pagination as d, isValidChannelSlug as i, toChannelSlug as t, validateChannelSlug as v };

package/dist/{api-DYrG_5uC.d.ts → api-Dgp2k2ZF.d.ts}

@@ -71,6 +71,86 @@ declare class NetworkError extends PushFloError {
     toJSON(): Record<string, unknown>;
 }
 
+/**
+ * Error thrown when input validation fails
+ */
+declare class ValidationError extends PushFloError {
+    /** The field that failed validation */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+    /**
+     * Create an error for an invalid channel slug
+     */
+    static invalidChannelSlug(slug: string): ValidationError;
+    /**
+     * Create an error for a required field
+     */
+    static required(field: string): ValidationError;
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Channel slug validation utilities
+ *
+ * Channel slugs must follow these rules:
+ * - 1-64 characters long
+ * - Lowercase letters (a-z), numbers (0-9), and hyphens (-) only
+ * - Cannot start or end with a hyphen
+ * - Cannot have consecutive hyphens
+ */
+/** Maximum length for a channel slug */
+declare const MAX_SLUG_LENGTH = 64;
+/** Minimum length for a channel slug */
+declare const MIN_SLUG_LENGTH = 1;
+/**
+ * Check if a channel slug is valid
+ *
+ * @param slug - The channel slug to validate
+ * @returns true if the slug is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidChannelSlug('my-channel')     // true
+ * isValidChannelSlug('channel-123')    // true
+ * isValidChannelSlug('a')              // true
+ * isValidChannelSlug('My-Channel')     // false (uppercase)
+ * isValidChannelSlug('-channel')       // false (starts with hyphen)
+ * isValidChannelSlug('channel:name')   // false (contains colon)
+ * isValidChannelSlug('channel_name')   // false (contains underscore)
+ * ```
+ */
+declare function isValidChannelSlug(slug: string): boolean;
+/**
+ * Convert a string to a valid channel slug
+ *
+ * @param str - The string to convert
+ * @returns A valid channel slug
+ *
+ * @example
+ * ```typescript
+ * toChannelSlug('My Channel')           // 'my-channel'
+ * toChannelSlug('Hello World!')         // 'hello-world'
+ * toChannelSlug('user:123:messages')    // 'user-123-messages'
+ * toChannelSlug('___test___')           // 'test'
+ * ```
+ */
+declare function toChannelSlug(str: string): string;
+/**
+ * Validation result with detailed error information
+ */
+interface SlugValidationResult {
+    valid: boolean;
+    error?: string;
+    suggestion?: string;
+}
+/**
+ * Validate a channel slug with detailed error messages
+ *
+ * @param slug - The channel slug to validate
+ * @returns Validation result with error details and suggestions
+ */
+declare function validateChannelSlug(slug: string): SlugValidationResult;
+
 /**
  * A PushFlo channel
  */
@@ -146,4 +226,4 @@ interface Pagination {
     totalPages: number;
 }
 
-export { AuthenticationError as A, type Channel as C, type ListChannelsOptions as L, NetworkError as N, PushFloError as P, type ChannelInput as a, type ChannelUpdateInput as b, type Pagination as c };
+export { AuthenticationError as A, type Channel as C, type ListChannelsOptions as L, MAX_SLUG_LENGTH as M, NetworkError as N, PushFloError as P, type SlugValidationResult as S, ValidationError as V, type ChannelInput as a, type ChannelUpdateInput as b, MIN_SLUG_LENGTH as c, type Pagination as d, isValidChannelSlug as i, toChannelSlug as t, validateChannelSlug as v };

package/dist/index.cjs

@@ -279,6 +279,117 @@ var AuthenticationError = class _AuthenticationError extends PushFloError {
   }
 };
 
+// src/errors/ValidationError.ts
+var ValidationError = class _ValidationError extends PushFloError {
+  /** The field that failed validation */
+  field;
+  constructor(message, field) {
+    super(message, "VALIDATION_ERROR", { retryable: false });
+    this.name = "ValidationError";
+    this.field = field;
+  }
+  /**
+   * Create an error for an invalid channel slug
+   */
+  static invalidChannelSlug(slug) {
+    return new _ValidationError(
+      `Invalid channel slug '${slug}': must be 1-64 characters, lowercase alphanumeric with hyphens, cannot start or end with a hyphen`,
+      "slug"
+    );
+  }
+  /**
+   * Create an error for a required field
+   */
+  static required(field) {
+    return new _ValidationError(`${field} is required`, field);
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      field: this.field
+    };
+  }
+};
+
+// src/utils/validation.ts
+var MAX_SLUG_LENGTH = 64;
+var MIN_SLUG_LENGTH = 1;
+var SLUG_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function isValidChannelSlug(slug) {
+  if (!slug || typeof slug !== "string") {
+    return false;
+  }
+  if (slug.length < MIN_SLUG_LENGTH || slug.length > MAX_SLUG_LENGTH) {
+    return false;
+  }
+  if (slug.includes("--")) {
+    return false;
+  }
+  return SLUG_REGEX.test(slug);
+}
+function toChannelSlug(str) {
+  return str.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, MAX_SLUG_LENGTH);
+}
+function validateChannelSlug(slug) {
+  if (!slug || typeof slug !== "string") {
+    return {
+      valid: false,
+      error: "Channel slug is required"
+    };
+  }
+  if (slug.length < MIN_SLUG_LENGTH) {
+    return {
+      valid: false,
+      error: "Channel slug cannot be empty"
+    };
+  }
+  if (slug.length > MAX_SLUG_LENGTH) {
+    return {
+      valid: false,
+      error: `Channel slug cannot exceed ${MAX_SLUG_LENGTH} characters (got ${slug.length})`,
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  if (slug !== slug.toLowerCase()) {
+    return {
+      valid: false,
+      error: "Channel slug must be lowercase",
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  if (slug.startsWith("-")) {
+    return {
+      valid: false,
+      error: "Channel slug cannot start with a hyphen",
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  if (slug.endsWith("-")) {
+    return {
+      valid: false,
+      error: "Channel slug cannot end with a hyphen",
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  if (slug.includes("--")) {
+    return {
+      valid: false,
+      error: "Channel slug cannot contain consecutive hyphens",
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  const invalidChars = slug.match(/[^a-z0-9-]/g);
+  if (invalidChars) {
+    const uniqueChars = [...new Set(invalidChars)].join(", ");
+    return {
+      valid: false,
+      error: `Channel slug contains invalid characters: ${uniqueChars}. Only lowercase letters, numbers, and hyphens are allowed.`,
+      suggestion: toChannelSlug(slug)
+    };
+  }
+  return { valid: true };
+}
+
 // src/utils/retry.ts
 function calculateBackoff(attempt, options = {}) {
   const {
@@ -1024,11 +1135,16 @@ var PushFloClient = class extends TypedEventEmitter {
   }
   /**
    * Subscribe to a channel
+   *
+   * @throws {ValidationError} If the channel slug is invalid
    */
   subscribe(channel, options = {}) {
     if (!channel) {
       throw new PushFloError("Channel is required", "INVALID_CHANNEL", { retryable: false });
     }
+    if (!isValidChannelSlug(channel)) {
+      throw ValidationError.invalidChannelSlug(channel);
+    }
     this.logger.debug("Subscribing to channel:", channel);
     this.subscriptions.add(channel, options);
     if (this.wsManager.state === "connected") {
@@ -1203,8 +1319,14 @@ var NetworkError = class _NetworkError extends PushFloError {
 
 exports.AuthenticationError = AuthenticationError;
 exports.ConnectionError = ConnectionError;
+exports.MAX_SLUG_LENGTH = MAX_SLUG_LENGTH;
+exports.MIN_SLUG_LENGTH = MIN_SLUG_LENGTH;
 exports.NetworkError = NetworkError;
 exports.PushFloClient = PushFloClient;
 exports.PushFloError = PushFloError;
+exports.ValidationError = ValidationError;
+exports.isValidChannelSlug = isValidChannelSlug;
+exports.toChannelSlug = toChannelSlug;
+exports.validateChannelSlug = validateChannelSlug;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map