README

Official PHP SDK for the StoryGrab API.
Covers both the Partner API (for third-party integrations) and the Mobile API (for user-facing apps).

Requirements

Installation

composer require storygrab/php-sdk

Quick Start

Partner API

use StoryGrab\StoryGrabClient;

$client = StoryGrabClient::partner(
    apiToken: 'YOUR_PARTNER_API_TOKEN',
    baseUrl:  'https://app.storygrab.io'  // optional, defaults to this
);

// List all authorized profiles
$profiles = $client->partner()->profiles();
foreach ($profiles as $profile) {
    echo $profile->username . PHP_EOL;
}

// Get a single profile
$profile = $client->partner()->profile('nasa');

// Get paginated posts for a profile
$page = $client->partner()->profilePosts('nasa', perPage: 50);
foreach ($page->data as $post) {
    echo $post->shortcode . ' – ' . $post->caption . PHP_EOL;
}

// Next page
if ($page->hasMorePages()) {
    $nextPage = $client->partner()->profilePosts('nasa', perPage: 50, page: 2);
}

// All posts across every authorized profile
$posts = $client->partner()->posts(perPage: 30, page: 1);

// Latest stories (up to 50)
$stories = $client->partner()->latestStories(limit: 20);

// Create a video embed
$embed = $client->partner()->createVideoEmbed(
    videoUrl:   'https://cdn.example.com/video.mp4',
    expiresIn:  3600  // 1 hour
);
echo $embed->embedUrl; // https://app.storygrab.io/embed/v/<token>

Mobile API

use StoryGrab\StoryGrabClient;

$client = StoryGrabClient::mobile('https://app.storygrab.io');

// Authenticate (token is automatically applied to subsequent requests)
$auth = $client->mobile()->login(
    email:      'user@example.com',
    password:   'secret',
    deviceName: 'my-app-v1'
);
echo 'Logged in as: ' . $auth->user->name;

// Register a new account
$auth = $client->mobile()->register(
    name:            'Ada Lovelace',
    email:           'ada@example.com',
    password:        'secure-pass',
    passwordConfirm: 'secure-pass',
    deviceName:      'my-app'
);

// Get the authenticated user's profile
$user = $client->mobile()->user();

// Paginated feed
$feed = $client->mobile()->feed(perPage: 20);
foreach ($feed->data as $post) {
    echo $post->caption . PHP_EOL;
}

// Latest stories
$stories = $client->mobile()->stories(limit: 30);

// Search
$results = $client->mobile()->search('space telescope');
// $results['profiles'] => Profile[]
// $results['posts']    => Post[]

// Bookmarks
$bookmarks = $client->mobile()->bookmarks();

// Toggle bookmark
$status = $client->mobile()->toggleBookmark('post-ulid-here');
// 'added' | 'removed'

// Logout
$client->mobile()->logout();

Error Handling

All SDK methods throw typed exceptions on non-2xx responses:

use StoryGrab\Exceptions\AuthenticationException;
use StoryGrab\Exceptions\NotFoundException;
use StoryGrab\Exceptions\ValidationException;
use StoryGrab\Exceptions\RateLimitException;
use StoryGrab\Exceptions\ApiException;

try {
    $profile = $client->partner()->profile('unknown-handle');
} catch (NotFoundException $e) {
    echo 'Profile not found: ' . $e->getMessage();
} catch (AuthenticationException $e) {
    echo 'Invalid or expired token.';
} catch (ValidationException $e) {
    // Field-level errors as ['field' => ['error message', ...]]
    print_r($e->getErrors());
} catch (RateLimitException $e) {
    echo 'Slow down! Retry after a moment.';
} catch (ApiException $e) {
    echo 'API error ' . $e->getStatusCode() . ': ' . $e->getMessage();
}

Data Objects

All responses are returned as immutable typed DTOs (PHP 8.1 readonly properties):

Advanced Usage

Paginating through all pages

$page    = 1;
$allPosts = [];

do {
    $result   = $client->partner()->posts(perPage: 100, page: $page);
    $allPosts = array_merge($allPosts, $result->data);
    $page++;
} while ($result->hasMorePages());

Fetching everything at once (per_page=all)

$all = $client->partner()->profilePosts('nasa', perPage: 'all');

Using a custom Guzzle client

use GuzzleHttp\Client;
use StoryGrab\StoryGrabClient;

$http   = new Client(['base_uri' => 'https://my-proxy.example.com/api/v1/partner/', 'timeout' => 60]);
$client = StoryGrabClient::withHttpClient($http);

Swapping the token at runtime

$client->setToken('new-token-after-rotation');

Running Tests

composer install
composer test

License

MIT © StoryGrab