@socialcrow/sdk

Official TypeScript SDK for the SocialCrow API.

Installation

npm install @socialcrow/sdk
# or
pnpm add @socialcrow/sdk
# or
yarn add @socialcrow/sdk

Requires Node.js 18 or later.

Quick Start

import { SocialCrowClient } from "@socialcrow/sdk";

const client = new SocialCrowClient({ apiKey: "sk_live_..." });

const result = await client.orders.create({
  serviceId: "1234",
  link: "https://instagram.com/username",
  quantity: 1000,
});

if (!result.ok) {
  console.error(result.error.code, result.error.message);
} else {
  console.log("Order created:", result.data.orderId);
}

Error Handling

Every method returns Result<T> — it never throws. Always check result.ok before accessing result.data.

const result = await client.balance.get();

if (result.ok) {
  console.log(result.data.balance); // "12.5000"
} else {
  // result.error is typed as ApiError
  console.error(result.error.code);    // e.g. "UNAUTHORIZED"
  console.error(result.error.message); // human-readable description
}

Requests time out after 10 seconds and return { ok: false, error: { code: "NETWORK_ERROR", message: "Request timed out after 10 seconds." } }.

Resources

client.services

// List all available services
const result = await client.services.list();
// result.data → Service[]

client.orders

// Create an order
const result = await client.orders.create({
  serviceId: "1234",
  link: "https://instagram.com/username",
  quantity: 1000,
  // Optional for drip-feed services:
  runs: 10,
  interval: 60, // minutes between runs
  // Optional for comment-type services:
  comments: ["Great post!", "Love this"],
});
// result.data → { orderId: string }

// Get a single order's status
const result = await client.orders.status("ABC123456789DE");
// result.data → OrderDetail

// Get status for up to 100 orders in one request
const result = await client.orders.statusBulk(["ABC123456789DE", "BBB123456789DE"]);
// result.data → Record<string, OrderDetail | { error: string }>

// List your orders (paginated)
const result = await client.orders.list({ page: 1 });
// result.data → { orders: OrderSummary[], page, pageSize, total, totalPages }

client.balance

const result = await client.balance.get();
// result.data → { balance: "12.5000", currency: "USD" }

client.refills

Refills let you re-deliver followers/views/etc. for an order whose count has dropped. The service must have refill: true.

// Request a refill for a single order
const result = await client.refills.request("ABC123456789DE");
// result.data → { refillId: string, orderId: string, status: "pending" }
// Returns REFILL_NOT_ELIGIBLE if the service doesn't support refills.

// Get the refill status for an order
const result = await client.refills.get("ABC123456789DE");
// result.data → RefillStatusResult

// Request refills for up to 100 orders at once
const result = await client.refills.bulkRequest(["ABC123456789DE", "BBB123456789DE"]);
// result.data → Record<string, RefillCreateResult | { error: string }>

// Get refill status for up to 100 orders at once
const result = await client.refills.bulkStatus(["ABC123456789DE", "BBB123456789DE"]);
// result.data → Record<string, RefillStatusResult | { error: string }> 

Configuration

const client = new SocialCrowClient({
  apiKey: "sk_live_...",      // required
  baseUrl: "https://...",    // optional — defaults to https://www.socialcrow.co
});

Error Codes

| Code | Description | |---|---| | UNAUTHORIZED | Invalid or missing API key | | SERVICE_NOT_FOUND | The requested service does not exist | | SERVICE_INACTIVE | The service is currently disabled | | INVALID_QUANTITY | Quantity is outside the service min/max range | | INVALID_LINK | The link field is missing or malformed | | MISSING_COMMENTS | Comment-type service requires a comments array | | DRIPFEED_NOT_SUPPORTED | Drip-feed params sent for a non-drip-feed service | | INVALID_DRIPFEED_PARAMS | Invalid runs or interval values | | INSUFFICIENT_BALANCE | Account balance too low to cover the order | | ORDER_NOT_FOUND | Order ID does not exist or belongs to another account | | TOO_MANY_ORDERS | Bulk request exceeded the 100-order limit | | REFILL_NOT_ELIGIBLE | Service does not support automatic refills | | INVALID_REQUEST | General validation failure — see error.message for details | | RATE_LIMITED | Too many requests — back off and retry | | INTERNAL_ERROR | Unexpected server error | | NETWORK_ERROR | Request failed at the network level (DNS, timeout, connection refused) |

TypeScript

All request and response types are exported:

import type {
  SocialCrowClientConfig,
  Service,
  OrderCreateParams,
  OrderCreateResult,
  OrderDetail,
  OrderSummary,
  OrderListParams,
  OrderListResult,
  OrderStatus,
  BulkOrderStatusResult,
  RefillCreateResult,
  RefillStatusResult,
  RefillStatus,
  BulkRefillCreateResult,
  BulkRefillStatusResult,
  BalanceResult,
  Result,
  ApiError,
  ApiErrorCode,
} from "@socialcrow/sdk";