npm package: @socialcrow/sdk
Description: Official TypeScript SDK for the SocialCrow API
Author: SocialCrow
Latest version: 1.0.1

# @socialcrow/sdk

Official TypeScript SDK for the [SocialCrow](https://www.socialcrow.co) API.

## Installation

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

Requires Node.js 18 or later.

## Quick Start

```ts
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`.

```ts
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`

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

### `client.orders`

```ts
// 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`

```ts
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`.

```ts
// 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

```ts
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:

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