arkaos 4.26.0 → 4.28.0

package/departments/marketing/tools/integrations/plivo.md

@@ -0,0 +1,140 @@
+# Plivo
+
+Cloud communications API platform — SMS, MMS, voice, WhatsApp. Direct Twilio competitor with similar pricing and developer-first positioning.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API |
+| MCP | - | Not available |
+| CLI | - | None official |
+| SDK | ✓ | Node, Python, Ruby, PHP, Java, Go, .NET |
+
+## Authentication
+
+- **Type**: Basic auth with Auth ID + Auth Token
+- **Header**: `Authorization: Basic base64(AuthID:AuthToken)`
+- **Get credentials**: https://console.plivo.com → Account → Account Settings
+- **Note**: Subaccounts available for isolating environments or customers
+
+## Common Agent Operations
+
+### Send SMS
+
+```bash
+POST https://api.plivo.com/v1/Account/{AuthID}/Message/
+
+{
+  "src": "+15559876543",
+  "dst": "+15551234567",
+  "text": "Hello from Plivo"
+}
+```
+
+### Send MMS
+
+```bash
+POST https://api.plivo.com/v1/Account/{AuthID}/Message/
+
+{
+  "src": "+15559876543",
+  "dst": "+15551234567",
+  "text": "Check this out",
+  "type": "mms",
+  "media_urls": ["https://example.com/image.jpg"]
+}
+```
+
+### Bulk send (powerpack)
+
+Use Plivo's Powerpack feature to send from a pool of numbers with sticky sender + automatic A2P registration. Configured in console; messages then sent with `powerpack_uuid` instead of `src`.
+
+```bash
+POST https://api.plivo.com/v1/Account/{AuthID}/Message/
+
+{
+  "powerpack_uuid": "...",
+  "dst": "+15551234567",
+  "text": "Hello"
+}
+```
+
+### Get message details
+
+```bash
+GET https://api.plivo.com/v1/Account/{AuthID}/Message/{MessageUUID}/
+```
+
+### List messages
+
+```bash
+GET https://api.plivo.com/v1/Account/{AuthID}/Message/?limit=20&offset=0
+```
+
+### Rent a phone number
+
+```bash
+# Search available
+GET https://api.plivo.com/v1/Account/{AuthID}/PhoneNumber/?country_iso=US&type=local
+
+# Rent
+POST https://api.plivo.com/v1/Account/{AuthID}/PhoneNumber/{NumberID}/
+```
+
+### Configure inbound message webhook on an Application
+
+```bash
+POST https://api.plivo.com/v1/Account/{AuthID}/Application/
+
+{
+  "app_name": "SMS Receiver",
+  "message_url": "https://your-app.com/sms-webhook",
+  "message_method": "POST"
+}
+```
+
+Then assign the application to the phone number.
+
+### A2P 10DLC registration (US)
+
+Configured through console UI under Compliance. Programmatic registration available for high-volume customers via dedicated API endpoints (request access).
+
+## API Pattern
+
+REST + JSON. Pagination via `limit` + `offset`. Webhook callbacks for inbound messages and delivery status (configured per-application).
+
+## Pricing
+
+- US 10DLC SMS: $0.0055/msg (typically lower than Twilio)
+- US toll-free SMS: $0.0055/msg
+- US short code SMS: similar + monthly lease
+- MMS: ~$0.02
+- Carrier surcharges layered on top
+- Phone number rental: ~$0.80/mo local, ~$1/mo toll-free
+
+Plivo typically prices 5–20% under Twilio at the per-send level. Less of an ecosystem advantage but real cost savings at high volume.
+
+## Rate Limits
+
+- Default: 1 msg/sec
+- Powerpacks scale throughput based on number pool size and A2P trust
+- Short codes: 100+ msg/sec
+
+## When to Use
+
+- Custom SMS build, want a Twilio-like API with lower cost
+- High-volume sending where the per-message delta matters
+- Want bulk sending with sticky sender via Powerpack
+- B2B SaaS embedding SMS or transactional/auth at scale
+
+## When NOT to Use
+
+- DTC ecom marketing flows — Klaviyo, Postscript, Attentive
+- Ecosystem matters more than price — Twilio's broader product surface (Voice, Studio, SendGrid, Segment, etc.) wins
+- Need mature WhatsApp Business — Twilio has deeper WhatsApp tooling
+
+## Relevant Skills
+
+- sms
+- onboarding (post-signup notifications)

package/departments/marketing/tools/integrations/posthog.md

@@ -0,0 +1,151 @@
+# PostHog
+
+Open-source product analytics with session replay and feature flags.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | Capture API, Query API, Feature Flags API |
+| MCP | - | Not available |
+| CLI | ✓ | `posthog` CLI for local development |
+| SDK | ✓ | JavaScript, Python, Ruby, Go, etc. |
+
+## Authentication
+
+- **Type**: API Key (Personal or Project)
+- **Header**: `Authorization: Bearer {api_key}`
+- **For capture**: Project API Key in payload
+
+## Common Agent Operations
+
+### Capture event
+
+```bash
+POST https://app.posthog.com/capture/
+
+{
+  "api_key": "{project_api_key}",
+  "event": "signup_completed",
+  "distinct_id": "user_123",
+  "properties": {
+    "plan": "pro",
+    "$current_url": "https://example.com/signup"
+  }
+}
+```
+
+### Batch events
+
+```bash
+POST https://app.posthog.com/batch/
+
+{
+  "api_key": "{project_api_key}",
+  "batch": [
+    {"event": "pageview", "distinct_id": "user_1"},
+    {"event": "signup", "distinct_id": "user_2"}
+  ]
+}
+```
+
+### Get person by distinct_id
+
+```bash
+GET https://app.posthog.com/api/projects/{project_id}/persons/?distinct_id=user_123
+
+Authorization: Bearer {api_key}
+```
+
+### Query events (HogQL)
+
+```bash
+POST https://app.posthog.com/api/projects/{project_id}/query/
+
+{
+  "query": {
+    "kind": "HogQLQuery",
+    "query": "SELECT event, count() FROM events WHERE timestamp > now() - interval 7 day GROUP BY event ORDER BY count() DESC LIMIT 10"
+  }
+}
+```
+
+### Get feature flag value
+
+```bash
+POST https://app.posthog.com/decide?v=3
+
+{
+  "api_key": "{project_api_key}",
+  "distinct_id": "user_123"
+}
+```
+
+### Get insights
+
+```bash
+GET https://app.posthog.com/api/projects/{project_id}/insights/
+
+Authorization: Bearer {api_key}
+```
+
+### Get session recordings
+
+```bash
+GET https://app.posthog.com/api/projects/{project_id}/session_recordings/
+
+Authorization: Bearer {api_key}
+```
+
+## JavaScript SDK
+
+```javascript
+// Initialize
+posthog.init('PROJECT_API_KEY', {
+  api_host: 'https://app.posthog.com'
+});
+
+// Identify user
+posthog.identify('user_123', {
+  email: 'user@example.com',
+  plan: 'pro'
+});
+
+// Track event
+posthog.capture('signup_completed', {
+  method: 'email'
+});
+
+// Check feature flag
+if (posthog.isFeatureEnabled('new-pricing')) {
+  // Show new pricing
+}
+```
+
+## Key Features
+
+- **Event tracking** - Product analytics
+- **Session replay** - Watch user sessions
+- **Feature flags** - Control feature rollout
+- **A/B testing** - Built-in experiments
+- **HogQL** - SQL-like query language
+- **Self-hostable** - Run on your infrastructure
+
+## When to Use
+
+- Product analytics with privacy focus
+- Session replay for UX insights
+- Feature flag management
+- Self-hosted analytics needs
+- Open-source requirements
+
+## Rate Limits
+
+- Cloud: 10,000 events/second
+- Self-hosted: Unlimited
+
+## Relevant Skills
+
+- analytics
+- ab-testing
+- onboarding

package/departments/marketing/tools/integrations/postmark.md

@@ -0,0 +1,234 @@
+# Postmark
+
+Transactional email delivery service with fast delivery, templates, bounce management, and detailed analytics.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API for email sending, templates, bounces, stats |
+| MCP | - | Not available |
+| CLI | ✓ | [postmark.js](../clis/postmark.js) |
+| SDK | ✓ | Node.js, Ruby, Python, PHP, Java, .NET, Go |
+
+## Authentication
+
+- **Type**: Server Token (or Account Token for account-level ops)
+- **Header**: `X-Postmark-Server-Token: {server_token}` (server-level)
+- **Header**: `X-Postmark-Account-Token: {account_token}` (account-level)
+- **Get key**: API Tokens tab at https://account.postmarkapp.com/servers
+- **Note**: Server tokens are per-server; account tokens apply across all servers
+
+## Common Agent Operations
+
+### Send single email
+
+```bash
+POST https://api.postmarkapp.com/email
+
+{
+  "From": "sender@example.com",
+  "To": "recipient@example.com",
+  "Subject": "Welcome!",
+  "HtmlBody": "<html><body><p>Hello!</p></body></html>",
+  "TextBody": "Hello!",
+  "MessageStream": "outbound",
+  "TrackOpens": true,
+  "TrackLinks": "HtmlAndText"
+}
+```
+
+### Send with template
+
+```bash
+POST https://api.postmarkapp.com/email/withTemplate
+
+{
+  "From": "sender@example.com",
+  "To": "recipient@example.com",
+  "TemplateId": 12345,
+  "TemplateModel": {
+    "name": "Jane",
+    "action_url": "https://example.com/verify"
+  },
+  "MessageStream": "outbound"
+}
+```
+
+### Send batch emails
+
+```bash
+POST https://api.postmarkapp.com/email/batch
+
+[
+  {
+    "From": "sender@example.com",
+    "To": "user1@example.com",
+    "Subject": "Notification",
+    "TextBody": "Hello user 1"
+  },
+  {
+    "From": "sender@example.com",
+    "To": "user2@example.com",
+    "Subject": "Notification",
+    "TextBody": "Hello user 2"
+  }
+]
+```
+
+### List templates
+
+```bash
+GET https://api.postmarkapp.com/templates?Count=100&Offset=0
+```
+
+### Get template
+
+```bash
+GET https://api.postmarkapp.com/templates/{templateIdOrAlias}
+```
+
+### Create template
+
+```bash
+POST https://api.postmarkapp.com/templates
+
+{
+  "Name": "Welcome Email",
+  "Alias": "welcome",
+  "Subject": "Welcome {{name}}!",
+  "HtmlBody": "<html><body><p>Hello {{name}}</p></body></html>",
+  "TextBody": "Hello {{name}}"
+}
+```
+
+### Get delivery stats
+
+```bash
+GET https://api.postmarkapp.com/deliverystats
+```
+
+### List bounces
+
+```bash
+GET https://api.postmarkapp.com/bounces?count=50&offset=0&type=HardBounce
+```
+
+### Activate bounce (reactivate recipient)
+
+```bash
+PUT https://api.postmarkapp.com/bounces/{bounceId}/activate
+```
+
+### Search outbound messages
+
+```bash
+GET https://api.postmarkapp.com/messages/outbound?count=50&offset=0&recipient=user@example.com
+```
+
+### Get outbound stats overview
+
+```bash
+GET https://api.postmarkapp.com/stats/outbound?fromdate=2025-01-01&todate=2025-01-31
+```
+
+### Get open stats
+
+```bash
+GET https://api.postmarkapp.com/stats/outbound/opens?fromdate=2025-01-01&todate=2025-01-31
+```
+
+### Get click stats
+
+```bash
+GET https://api.postmarkapp.com/stats/outbound/clicks?fromdate=2025-01-01&todate=2025-01-31
+```
+
+### Get server info
+
+```bash
+GET https://api.postmarkapp.com/server
+```
+
+### List suppressions
+
+```bash
+GET https://api.postmarkapp.com/message-streams/outbound/suppressions/dump
+```
+
+### Create suppression
+
+```bash
+POST https://api.postmarkapp.com/message-streams/outbound/suppressions
+
+{
+  "Suppressions": [
+    { "EmailAddress": "user@example.com" }
+  ]
+}
+```
+
+## API Pattern
+
+Postmark uses simple REST endpoints with PascalCase field names in request/response bodies. Authentication is via custom headers rather than Authorization. Pagination uses `Count` and `Offset` parameters. Email sending is synchronous with immediate delivery confirmation.
+
+## Key Metrics
+
+### Delivery Metrics
+- `Sent` - Total emails sent
+- `Bounced` - Bounce count by type (hard, soft, transient)
+- `SpamComplaints` - Spam complaint count
+- `Opens` - Open count and unique opens
+- `Clicks` - Click count and unique clicks
+
+### Bounce Types
+- `HardBounce` - Permanent delivery failure
+- `SoftBounce` - Temporary delivery failure
+- `Transient` - Temporary issue (retry)
+- `SpamNotification` - Marked as spam
+
+### Message Fields
+- `MessageID` - Unique message identifier
+- `SubmittedAt` - Submission timestamp
+- `Status` - Delivery status
+- `Recipients` - Recipient list
+
+## Parameters
+
+### Email Parameters
+- `From` - Sender address (must be verified)
+- `To` - Recipient (comma-separated for multiple)
+- `Subject` - Email subject
+- `HtmlBody` / `TextBody` - Email content
+- `MessageStream` - outbound (transactional) or broadcast
+- `TrackOpens` - Enable open tracking (boolean)
+- `TrackLinks` - None, HtmlAndText, HtmlOnly, TextOnly
+- `Tag` - Custom tag for categorization
+
+### Stats Parameters
+- `fromdate` - Start date (YYYY-MM-DD)
+- `todate` - End date (YYYY-MM-DD)
+- `tag` - Filter by tag
+
+## When to Use
+
+- Transactional emails (password resets, order confirmations, notifications)
+- Template-based email sending with dynamic variables
+- Monitoring email deliverability and bounce rates
+- Tracking email engagement (opens, clicks)
+- Managing email suppressions and bounces
+- High-reliability email delivery with fast performance
+
+## Rate Limits
+
+- 500 messages per batch request
+- 10 MB max per single message (including attachments)
+- 50 MB max per batch request
+- API rate limits vary by plan
+
+## Relevant Skills
+
+- emails
+- transactional-email
+- email-deliverability
+- onboarding-email

package/departments/marketing/tools/integrations/postscript.md

@@ -0,0 +1,126 @@
+# Postscript
+
+SMS marketing platform built for Shopify direct-to-consumer brands. Deepest Shopify integration of any SMS platform.
+
+## Capabilities
+
+| Integration | Available | Notes |
+|-------------|-----------|-------|
+| API | ✓ | REST API |
+| MCP | - | Not available |
+| CLI | - | None |
+| SDK | - | Use API directly |
+
+## Authentication
+
+- **Type**: API Key
+- **Header**: `Authorization: Bearer {api_key}` or `X-Postscript-Api-Key: {api_key}`
+- **Get key**: Postscript dashboard → Settings → API
+- **Note**: Keys are scoped per shop
+
+## Common Agent Operations
+
+### Search subscribers
+
+```bash
+GET https://api.postscript.io/api/v2/subscribers?phone_number=%2B15551234567
+```
+
+### Create subscriber (opt-in)
+
+```bash
+POST https://api.postscript.io/api/v2/subscribers
+
+{
+  "phone_number": "+15551234567",
+  "email": "user@example.com",
+  "first_name": "Jane",
+  "subscribed_at": "2026-05-15T10:00:00Z",
+  "opt_in_source": "checkout_keyword"
+}
+```
+
+Must include valid opt-in metadata for TCPA compliance.
+
+### Unsubscribe
+
+```bash
+DELETE https://api.postscript.io/api/v2/subscribers/{subscriberId}/subscription
+```
+
+### List keywords (e.g., JOIN, SAVE)
+
+```bash
+GET https://api.postscript.io/api/v2/keywords
+```
+
+### Send transactional message
+
+```bash
+POST https://api.postscript.io/api/v2/transactional/sms
+
+{
+  "phone_number": "+15551234567",
+  "message": "Your order #1234 shipped. Track at https://..."
+}
+```
+
+Transactional requires separate enablement; counts under transactional consent.
+
+### List campaigns
+
+```bash
+GET https://api.postscript.io/api/v2/campaigns
+```
+
+### List automations (flows)
+
+```bash
+GET https://api.postscript.io/api/v2/automations
+```
+
+### Webhooks
+
+Subscribe to events: `subscriber.created`, `subscriber.unsubscribed`, `message.delivered`, `message.failed`, `conversion.attributed`.
+
+## API Pattern
+
+REST + JSON. Standard `Bearer` auth. Pagination via `cursor` and `limit` (max 100).
+
+## Key Features
+
+- Native Shopify integration: purchases, abandoned carts, browse, product catalog auto-sync
+- Strong abandoned cart and browse abandonment automation builders
+- AI Reply (auto-reply trained on brand voice)
+- Conversational SMS / live agent for two-way
+- Opt-in tools: popups, keyword opt-in, checkout opt-in
+- A2P 10DLC managed in-platform
+- Reporting: revenue, click-through, conversion attribution, opt-out rate
+
+## Pricing
+
+- Plans: Starter (free, 1K msgs/mo), Growth ($100+/mo), Professional, Enterprise
+- Per-send pricing on top: ~$0.015 SMS, ~$0.04 MMS
+- Annual contracts standard at Growth+
+- Pricing scales meaningfully past 50K subscribers
+
+## When to Use
+
+- Shopify DTC brand wanting SMS-specific tooling (vs combined email/SMS)
+- Need deep abandoned cart, browse abandonment, post-purchase automation out of the box
+- Want managed A2P 10DLC + compliance tools
+- Mid-size DTC brand (10K–500K SMS subscribers)
+
+## When NOT to Use
+
+- Non-Shopify ecom — integration is shallow
+- Already on Klaviyo for email and SMS is secondary — Klaviyo SMS is simpler
+- Mid-market/enterprise needing concierge support — Attentive
+- Custom platform or B2B SaaS — Twilio
+
+## Relevant Skills
+
+- sms
+- emails (run alongside via Klaviyo or similar)
+- churn-prevention (win-back flows)
+- onboarding (post-purchase activation)