signalhouse-sms 1.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7839cdbf04383a2e3e68cabdc8502b0b1e3afb2b4d453a22d36fda2b223d1074
+  data.tar.gz: 47256138b86018a0f440f20f2e27f917bc006ea210243d0c791c4b9aeaa4d62a
+SHA512:
+  metadata.gz: fb0aef43119826e3d3e52b7fc7ff4d34b09c83d885bed508e2037c1327ef25a2d89888e69d29ec71e8d1aba7dd5b033049087c2b351ce74c5a4c401d72fbcfad
+  data.tar.gz: b43758fe7f2e721ed11dbc98affa398380c155638fce3249d60b66b1523440e2f05ba8d61c71cbaed543ce4dfc8718bfbcc0dcb1eebf86fe60d0e28cddf55d33

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,286 @@
+# SignalHouse Ruby SDK
+
+Official Ruby SDK for the [SignalHouse](https://signalhouse.io) SMS/MMS messaging API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "signalhouse-sms"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install signalhouse-sms
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```ruby
+require "signalhouse_sms"
+
+client = SignalHouseSms::Client.new(
+  api_key: "your-api-key",
+  base_url: "https://v2.signalhouse.io"
+)
+```
+
+For admin operations (SignalHouse internal staff):
+
+```ruby
+client = SignalHouseSms::Client.new(
+  api_key: "your-api-key",
+  base_url: "https://v2.signalhouse.io",
+  enable_admin: true
+)
+```
+
+### Login
+
+```ruby
+result = client.auth.login(email: "user@example.com", password: "password123")
+
+if result["success"]
+  token = result["data"]["token"]
+  puts "Logged in! Token: #{token}"
+else
+  puts "Login failed: #{result["error"]}"
+end
+```
+
+### Send an SMS
+
+```ruby
+result = client.messages.send_sms(
+  sender_phone_number: "15551234567",
+  recipient_phone_numbers: ["15559876543"],
+  message_body: "Hello from SignalHouse!",
+  token: "your-jwt-token"
+)
+
+puts result
+```
+
+### Send an MMS with Images
+
+```ruby
+image_file = {
+  filename: "photo.jpg",
+  io: File.open("photo.jpg", "rb"),
+  content_type: "image/jpeg"
+}
+
+result = client.messages.send_mms(
+  sender_phone_number: "15551234567",
+  recipient_phone_numbers: ["15559876543"],
+  message_body: "Check out this photo!",
+  images: [image_file],
+  token: "your-jwt-token"
+)
+
+puts result
+```
+
+### List Phone Numbers
+
+```ruby
+result = client.numbers.get_phone_numbers(
+  group_id: "G0000001",
+  page: 1,
+  limit: 20,
+  token: "your-jwt-token"
+)
+
+if result["success"]
+  result["data"]["data"].each do |number|
+    puts number["phoneNumber"]
+  end
+end
+```
+
+### Purchase Phone Numbers
+
+```ruby
+result = client.numbers.purchase_phone_number(
+  phone_numbers: ["15551234567"],
+  subgroup_id: "SG000001",
+  token: "your-jwt-token"
+)
+
+puts result
+```
+
+### Create a Brand
+
+```ruby
+result = client.brands.create_brand(
+  brand_data: {
+    subgroupId: "SG000001",
+    entityType: "PRIVATE_PROFIT",
+    displayName: "My Brand",
+    companyName: "My Company Inc",
+    ein: "123456789",
+    phone: "15551234567",
+    street: "123 Main St",
+    city: "New York",
+    state: "NY",
+    postalCode: "10001",
+    country: "US",
+    email: "contact@mycompany.com",
+    vertical: "TECHNOLOGY"
+  },
+  token: "your-jwt-token"
+)
+
+puts result
+```
+
+### Check a Toll-Free Business Verification
+
+When `required` is true and `status` is `NOT_STARTED`, submit the business verification with `submit_business_verification` before creating the group's first toll-free brand. Some groups verify each subgroup's business separately: a platform whose subgroups are separate businesses, set up by Signal House. For those groups `subgroup_id` is required, on both methods, and the response includes `subgroupId`.
+
+```ruby
+result = client.brands.get_business_verification(
+  group_id: "G0000001",
+  subgroup_id: "SG000001", # required when the group verifies each subgroup's business separately
+  token: "your-jwt-token"
+)
+
+if result["success"]
+  puts result["data"]["status"]
+end
+```
+
+### Using Token Override
+
+All methods accept a `token:` keyword to override the API key for that specific request. This is useful when making requests on behalf of authenticated users:
+
+```ruby
+# Use the client's api_key (default)
+result = client.brands.get_brands
+
+# Override with a specific user token
+result = client.brands.get_brands(token: "user-jwt-token")
+```
+
+### Custom Headers
+
+All methods accept a `headers:` keyword to add custom headers:
+
+```ruby
+result = client.brands.get_brands(
+  token: "user-jwt-token",
+  headers: { "X-Request-Id" => "abc123" }
+)
+```
+
+## Admin Methods
+
+When `enable_admin: true` is set, admin-scoped methods are available on domains that support them:
+
+```ruby
+client = SignalHouseSms::Client.new(
+  api_key: "admin-api-key",
+  base_url: "https://v2.signalhouse.io",
+  enable_admin: true
+)
+
+# Admin: list all groups
+client.groups.admin.get_groups(page: 1, limit: 50, token: admin_token)
+
+# Admin: approve a campaign
+client.campaigns.admin.approve_campaign(campaign_id: "C123", token: admin_token)
+
+# Admin: create subscription template
+client.subscriptions.admin.create_template(
+  template_data: { templateName: "Pro Plan", monthlyFee: 50_000_000 },
+  token: admin_token
+)
+
+# Admin: create internal user
+client.users.admin.create_internal_user(
+  data: { email: "admin@signalhouse.io", role: "signalhouse_admin" },
+  token: admin_token
+)
+```
+
+## Available Domains
+
+| Domain | Accessor | Methods |
+|--------|----------|---------|
+| Auth | `client.auth` | `login`, `reset_password`, `get_auth_history` |
+| Billing | `client.billing` | `get_transaction_history`, `get_wallet`, `update_wallet`, `get_payment_methods`, `add_funds`, `add_payment_method`, `remove_payment_method`, `get_invoice_details`, `get_fees` |
+| Brands | `client.brands` | `get_brands`, `get_external_vetting`, `create_brand`, `get_business_verification`, `submit_business_verification`, `get_toll_free_isv_account` (staff only), `set_toll_free_isv_account` (staff only), `transfer_brand`, `create_external_vetting`, `update_brand`, `revet_brand`, `delete_brand` |
+| Campaigns | `client.campaigns` | `get_campaigns`, `create_campaign`, `update_campaign`, `delete_campaign` |
+| Campaigns Admin | `client.campaigns.admin` | `approve_campaign`, `reject_campaign` |
+| Groups | `client.groups` | `get_group`, `update_group` |
+| Groups Admin | `client.groups.admin` | `get_groups`, `create_group`, `delete_group` |
+| Landings | `client.landings` | `get_landings`, `get_public_landing`, `create_landing`, `update_landing`, `get_landing_by_brand_id`, `delete_landing` |
+| Messages | `client.messages` | `get_messages`, `get_analytics`, `send_sms`, `send_mms`, `send_group_message`, `get_p2p_batch` |
+| Notifications | `client.notifications` | `get_notifications`, `update_notification_status`, `delete_notification` |
+| Numbers | `client.numbers` | `get_phone_numbers`, `get_number_health`, `get_available_phone_numbers`, `purchase_phone_number`, `update_phone_number`, `get_caller_name`, `set_caller_name`, `delete_caller_name`, `port_in_phone_number`, `assign_phone_number_to_campaign`, `unassign_phone_numbers_from_campaigns`, `delete_phone_numbers`, `transfer_phone_numbers`, `search_npa_nxx`, `lookup_locations` |
+| Shortlinks | `client.shortlinks` | `get_shortlink_redirect`, `get_shortlink` |
+| Subgroups | `client.subgroups` | `get_subgroups`, `create_subgroup`, `update_subgroup`, `delete_subgroup` |
+| Subscriptions | `client.subscriptions` | `get_subscriptions`, `subscribe`, `unsubscribe` |
+| Subscriptions Admin | `client.subscriptions.admin` | `get_templates`, `create_template`, `update_template`, `delete_template`, `create_custom_subscription` |
+| Templates | `client.templates` | `create`, `list`, `get`, `update`, `publish`, `archive`, `versions`, `validate`, `capabilities`, `upload_media` |
+| Users | `client.users` | `get_users`, `create_user`, `create_service_user`, `update_user`, `delete_user`, `get_notification_preferences`, `update_notification_preferences` |
+| Users Admin | `client.users.admin` | `get_users`, `create_internal_user` |
+| Webhooks | `client.webhooks` | `get_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook` |
+
+## Error Handling
+
+```ruby
+begin
+  result = client.messages.send_sms(
+    sender_phone_number: "15551234567",
+    recipient_phone_numbers: ["15559876543"],
+    message_body: "Hello!"
+  )
+rescue SignalHouseSms::ValidationError => e
+  puts "Validation error: #{e.message} (status: #{e.status})"
+rescue SignalHouseSms::Error => e
+  puts "SignalHouse error: #{e.message} (status: #{e.status})"
+end
+```
+
+## Response Format
+
+All methods return a standardized hash:
+
+**Success:**
+```ruby
+{
+  "success" => true,
+  "data"    => { ... },   # Parsed JSON response body
+  "status"  => 200        # HTTP status code
+}
+```
+
+**Error:**
+```ruby
+{
+  "success" => false,
+  "error"   => "Error message",
+  "status"  => 400        # HTTP status code
+}
+```
+
+## Requirements
+
+- Ruby >= 3.0.0
+- No external dependencies (uses `net/http` and `json` from stdlib)
+
+## License
+
+MIT

data/lib/signalhouse_sms/client.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SignalHouseSms
+  class Client
+    attr_reader :agents, :auth, :billing, :brands, :campaigns, :groups, :landings,
+                :messages, :notifications, :numbers, :registrations, :onboarding,
+                :shortlinks, :subgroups, :subscriptions, :templates, :tickets, :users, :voice, :webhooks
+
+    # Initialize a new SignalHouse client.
+    #
+    # @param api_key [String] Your SignalHouse API key (Bearer token)
+    # @param base_url [String] The base URL of the SignalHouse API
+    # @param enable_admin [Boolean] Whether to enable admin-only methods
+    def initialize(api_key:, base_url:, enable_admin: false)
+      raise SignalHouseSms::ValidationError.new("api_key") if api_key.nil? || api_key.to_s.strip.empty?
+      raise SignalHouseSms::ValidationError.new("base_url") if base_url.nil? || base_url.to_s.strip.empty?
+
+      json_client = HttpClient.new(base_url: base_url, api_key: api_key, multipart: false)
+      multipart_client = HttpClient.new(base_url: base_url, api_key: api_key, multipart: true)
+
+      @agents         = Agents.new(json_client, enable_admin)
+      @auth           = Auth.new(json_client, enable_admin)
+      @billing        = Billing.new(json_client, enable_admin)
+      @brands         = Brands.new(json_client, multipart_client, enable_admin)
+      @campaigns      = Campaigns.new(json_client, multipart_client, enable_admin)
+      @groups         = Groups.new(json_client, enable_admin)
+      @landings       = Landings.new(json_client, multipart_client, enable_admin)
+      @messages       = Messages.new(json_client, multipart_client, enable_admin)
+      @notifications  = Notifications.new(json_client, enable_admin)
+      @numbers        = Numbers.new(json_client, multipart_client, enable_admin)
+      @registrations = Registrations.new(json_client, enable_admin)
+      @onboarding     = Onboarding.new(json_client, enable_admin)
+      @shortlinks     = Shortlinks.new(json_client, enable_admin)
+      @subgroups      = Subgroups.new(json_client, enable_admin)
+      @subscriptions  = Subscriptions.new(json_client, enable_admin)
+      @templates      = Templates.new(json_client, multipart_client, enable_admin)
+      @tickets        = Tickets.new(json_client, enable_admin)
+      @users          = Users.new(json_client, enable_admin)
+      @voice          = Voice.new(json_client, enable_admin)
+      @webhooks       = Webhooks.new(json_client, enable_admin)
+    end
+  end
+end