PHPackages                             yannelli/pocket-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. yannelli/pocket-laravel

ActiveLibrary[API Development](/categories/api)

yannelli/pocket-laravel
=======================

Laravel SDK for the Pocket API - Access recordings, transcripts, summaries, and more

v1.2.0(2mo ago)2505—7.9%MITPHPPHP ^8.2CI passing

Since Dec 20Pushed 2mo agoCompare

[ Source](https://github.com/yannelli/pocket-laravel)[ Packagist](https://packagist.org/packages/yannelli/pocket-laravel)[ Docs](https://github.com/yannelli/pocket-laravel)[ GitHub Sponsors](https://github.com/:vendor_name)[ RSS](/packages/yannelli-pocket-laravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (28)Versions (5)Used By (0)

Pocket Laravel SDK
==================

[](#pocket-laravel-sdk)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e1921822378e46276bae0333eaeb135476017b3a9d5f2d14a33b5a6d60d204d5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f79616e6e656c6c692f706f636b65742d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/yannelli/pocket-laravel)[![GitHub Tests Action Status](https://camo.githubusercontent.com/fda7b936772afb86648aafd4556353bba0c0d093cfdbe98e89b238b24312aea3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f79616e6e656c6c692f706f636b65742d6c61726176656c2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/yannelli/pocket-laravel/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/72a593f3209747d9a1294b370f76cbe404e5db58006d5602b64dd78ebaa3cc23/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f79616e6e656c6c692f706f636b65742d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/yannelli/pocket-laravel)

- [Introduction](#introduction)
- [Installation](#installation)
    - [Configuration](#configuration)
- [Making Requests](#making-requests)
    - [Using the Facade](#using-the-facade)
    - [Using Dependency Injection](#using-dependency-injection)
    - [Multi-Tenant Applications](#multi-tenant-applications)
- [Recordings](#recordings)
    - [Retrieving Recordings](#retrieving-recordings)
    - [Filtering Recordings](#filtering-recordings)
    - [Iterating All Recordings](#iterating-all-recordings)
    - [Recording Details](#recording-details)
    - [Transcripts](#transcripts)
    - [Summaries](#summaries)
    - [Action Items](#action-items)
    - [Recording States](#recording-states)
- [Folders](#folders)
- [Tags](#tags)
- [Audio](#audio)
    - [Retrieving Audio URLs](#retrieving-audio-urls)
    - [Downloading Audio](#downloading-audio)
    - [Scoped Audio Resource](#scoped-audio-resource)
- [Error Handling](#error-handling)
- [Configuration Reference](#configuration-reference)
- [Testing](#testing)
- [Disclaimer](#disclaimer)

Introduction
------------

[](#introduction)

Pocket Laravel SDK provides an expressive, fluent interface for interacting with the [Pocket API](https://public.heypocketai.com/docs/index.html). Using this SDK, you may easily access your recordings, transcripts, summaries, and action items from within your Laravel application.

The SDK handles authentication, request building, pagination, retry logic with exponential backoff, and exception mapping—allowing you to focus on building your application rather than managing HTTP requests.

Installation
------------

[](#installation)

You may install the Pocket Laravel SDK via the Composer package manager:

```
composer require yannelli/pocket-laravel
```

After installing the package, the service provider will be automatically registered via Laravel's package discovery.

### Configuration

[](#configuration)

Before using the SDK, you will need to configure your Pocket API credentials. First, publish the configuration file using the `vendor:publish` Artisan command:

```
php artisan vendor:publish --tag="pocket-config"
```

This command will publish a `pocket.php` configuration file to your application's `config` directory:

```
return [
    'api_key' => env('POCKET_API_KEY'),
    'base_url' => env('POCKET_BASE_URL', 'https://public.heypocketai.com'),
    'api_version' => env('POCKET_API_VERSION', 'v1'),
    'timeout' => env('POCKET_TIMEOUT', 30),
    'retry' => [
        'times' => env('POCKET_RETRY_TIMES', 3),
        'sleep' => env('POCKET_RETRY_SLEEP', 1000),
    ],
];
```

Next, add your Pocket API key to your application's `.env` file:

```
POCKET_API_KEY=pk_your_api_key_here
```

Making Requests
---------------

[](#making-requests)

### Using the Facade

[](#using-the-facade)

The SDK provides a `Pocket` facade that allows you to fluently access all available resources:

```
use Yannelli\Pocket\Facades\Pocket;

// List recordings
$recordings = Pocket::recordings()->list();

// Get a specific recording
$recording = Pocket::recordings()->get('rec_123');

// List folders
$folders = Pocket::folders()->list();

// List tags
$tags = Pocket::tags()->list();
```

### Using Dependency Injection

[](#using-dependency-injection)

If you prefer dependency injection, you may type-hint the `Pocket` class in your controller's constructor or method signatures. The SDK's service provider binds the `Pocket` class as a singleton, ensuring the same instance is resolved throughout your application:

```
use Yannelli\Pocket\Pocket;

class RecordingController extends Controller
{
    public function __construct(
        private Pocket $pocket
    ) {}

    public function index()
    {
        return $this->pocket->recordings()->list();
    }
}
```

### Multi-Tenant Applications

[](#multi-tenant-applications)

For multi-tenant applications where each tenant may have their own Pocket API key, you may use the `withApiKey` method to create a new SDK instance with a different API key. All other configuration options are preserved from the original instance:

```
use Yannelli\Pocket\Facades\Pocket;

// Create a tenant-specific instance
$tenantPocket = Pocket::withApiKey($tenant->pocket_api_key);

// Use the tenant-specific instance
$recordings = $tenantPocket->recordings()->list();
```

You may also create multiple tenant instances from a single base configuration:

```
use Yannelli\Pocket\Pocket;

class TenantRecordingService
{
    public function __construct(
        private Pocket $pocket
    ) {}

    public function getRecordingsForTenant(Tenant $tenant)
    {
        return $this->pocket
            ->withApiKey($tenant->pocket_api_key)
            ->recordings()
            ->list();
    }
}
```

Note

The `withApiKey` method returns a new `Pocket` instance. The original instance remains unchanged, making it safe to use in concurrent or queued operations.

Recordings
----------

[](#recordings)

The recordings resource provides methods for listing, filtering, and retrieving recordings along with their associated transcripts, summaries, and action items.

### Retrieving Recordings

[](#retrieving-recordings)

To retrieve a paginated list of recordings, you may use the `list` method:

```
use Yannelli\Pocket\Facades\Pocket;

$recordings = Pocket::recordings()->list();

foreach ($recordings as $recording) {
    echo $recording->title;
    echo $recording->formattedDuration(); // "1:30:45"
}
```

The `list` method returns a `PaginatedRecordings` instance. You may check for additional pages and retrieve subsequent results:

```
if ($recordings->hasMore()) {
    $nextPage = Pocket::recordings()->list(page: $recordings->nextPage());
}
```

To retrieve a single recording by its ID, use the `get` method:

```
$recording = Pocket::recordings()->get('rec_123');
```

### Filtering Recordings

[](#filtering-recordings)

The recordings resource provides several convenient methods for filtering results. You may filter recordings by folder:

```
$recordings = Pocket::recordings()->inFolder('folder_123');
```

To filter by tags, pass an array of tag IDs to the `withTags` method:

```
$recordings = Pocket::recordings()->withTags(['tag_1', 'tag_2']);
```

You may also filter recordings within a specific date range:

```
$recordings = Pocket::recordings()->betweenDates('2025-01-01', '2025-01-31');
```

For more complex filtering, the `list` method accepts all filter parameters directly:

```
$recordings = Pocket::recordings()->list(
    folderId: 'folder_123',
    startDate: '2025-01-01',
    endDate: '2025-01-31',
    tagIds: ['tag_1', 'tag_2'],
    page: 1,
    limit: 50
);
```

### Iterating All Recordings

[](#iterating-all-recordings)

When you need to process all recordings, the `all` method returns a generator that automatically handles pagination:

```
foreach (Pocket::recordings()->all() as $recording) {
    echo $recording->title;
}
```

You may also apply filters when iterating all recordings:

```
foreach (Pocket::recordings()->all(folderId: 'folder_123') as $recording) {
    // Process recording...
}
```

Note

The `all` method uses PHP generators to efficiently iterate through large result sets without loading all recordings into memory at once.

### Recording Details

[](#recording-details)

When retrieving a single recording, you may control which related data is included in the response. By default, all related data is included. To exclude specific data and improve response times:

```
$recording = Pocket::recordings()->get(
    id: 'rec_123',
    includeTranscript: false,
    includeSummary: true,
    includeActionItems: true
);
```

### Transcripts

[](#transcripts)

Recordings may include transcript data with speaker identification and time-coded segments. You may access the transcript through the recording instance:

```
$recording = Pocket::recordings()->get('rec_123');

if ($recording->hasTranscript()) {
    // Access the full transcript text
    echo $recording->transcript->text;

    // Get a list of speakers
    $speakers = $recording->transcript->speakers();

    // Retrieve segments for a specific speaker
    $segments = $recording->transcript->segmentsForSpeaker('Speaker 1');
}
```

### Summaries

[](#summaries)

Recordings may include AI-generated summaries organized into sections:

```
if ($recording->hasSummary()) {
    echo $recording->summary->title;

    foreach ($recording->summary->sections as $section) {
        echo $section->heading;
        echo $section->content;
    }
}
```

### Action Items

[](#action-items)

Recordings may include extracted action items with priority levels and completion status:

```
if ($recording->hasActionItems()) {
    // Filter by status
    $pendingItems = $recording->pendingActionItems();
    $completedItems = $recording->completedActionItems();

    foreach ($recording->actionItems as $item) {
        echo $item->title;
        echo $item->priority->label(); // "High", "Medium", "Low"

        if ($item->isOverdue()) {
            // Handle overdue item...
        }
    }
}
```

### Recording States

[](#recording-states)

Recordings progress through various processing states. You may inspect a recording's current state using the following methods:

```
$recording = Pocket::recordings()->get('rec_123');

if ($recording->isProcessing()) {
    echo "Recording is being processed...";
}

if ($recording->isCompleted()) {
    echo "Recording is ready!";
}

if ($recording->isFailed()) {
    echo "Processing failed: " . $recording->state->description();
}
```

The available recording states are: `pending`, `transcribing`, `failed`, `transcribed`, `summarizing`, `summarization_failed`, `completed`, and `unknown`.

Folders
-------

[](#folders)

The folders resource allows you to list and retrieve folders:

```
use Yannelli\Pocket\Facades\Pocket;

// List all folders
$folders = Pocket::folders()->list();

// Find a folder by ID
$folder = Pocket::folders()->find('folder_123');

// Find a folder by name
$folder = Pocket::folders()->findByName('Work Meetings');

// Get the default folder
$defaultFolder = Pocket::folders()->default();
```

Tags
----

[](#tags)

The tags resource provides methods for listing and finding tags:

```
use Yannelli\Pocket\Facades\Pocket;

// List all tags (ordered by usage)
$tags = Pocket::tags()->list();

// Get most used tags
$topTags = Pocket::tags()->mostUsed(5);

// Find a tag by ID
$tag = Pocket::tags()->find('tag_123');

// Find a tag by name
$tag = Pocket::tags()->findByName('Important');
```

Audio
-----

[](#audio)

The audio resource provides methods for accessing and downloading audio files associated with recordings.

### Retrieving Audio URLs

[](#retrieving-audio-urls)

To get a signed URL for a recording's audio file:

```
use Yannelli\Pocket\Facades\Pocket;

$audioUrl = Pocket::audio()->getUrl('rec_123');

echo $audioUrl->signedUrl;
echo $audioUrl->expiresIn; // Seconds until expiry
```

Signed URLs expire after a period of time. You may check if a URL has expired and retrieve a fresh one:

```
if ($audioUrl->isExpired()) {
    $audioUrl = Pocket::audio()->getUrl('rec_123');
}
```

### Downloading Audio

[](#downloading-audio)

The SDK provides several methods for downloading audio content:

```
// Get the audio file contents as a string
$contents = Pocket::audio()->getContents('rec_123');

// Stream the audio file (memory efficient for large files)
$stream = Pocket::audio()->stream('rec_123');

// Download to a temporary file (auto-cleaned up on script end)
$tempPath = Pocket::audio()->download('rec_123');
```

You may also save audio files directly to Laravel's filesystem:

```
// Save to a Laravel storage disk
Pocket::audio()->saveTo('recordings/audio.mp3', 's3', [], 'rec_123');

// Save using streaming (memory efficient)
Pocket::audio()->saveStreamTo('recordings/audio.mp3', 'local', [], 'rec_123');

// Save directly to a local path
Pocket::audio()->saveToPath('/path/to/audio.mp3', 'rec_123');
```

To manually clean up temporary files created by the `download` method:

```
use Yannelli\Pocket\Resources\AudioResource;

AudioResource::cleanup();
```

### Scoped Audio Resource

[](#scoped-audio-resource)

When working with a single recording's audio, you may create a scoped audio resource to simplify method calls:

```
$audio = Pocket::audio('rec_123');

// All methods now work without passing the recording ID
$url = $audio->getUrl();
$contents = $audio->getContents();
$tempPath = $audio->download();
```

Error Handling
--------------

[](#error-handling)

The SDK throws specific exceptions based on the HTTP response status code. You may catch these exceptions to handle different error conditions:

```
use Yannelli\Pocket\Facades\Pocket;
use Yannelli\Pocket\Exceptions\AuthenticationException;
use Yannelli\Pocket\Exceptions\NotFoundException;
use Yannelli\Pocket\Exceptions\RateLimitException;
use Yannelli\Pocket\Exceptions\ValidationException;
use Yannelli\Pocket\Exceptions\ServerException;
use Yannelli\Pocket\Exceptions\PocketException;

try {
    $recording = Pocket::recordings()->get('rec_123');
} catch (AuthenticationException $e) {
    // Invalid API key (401)
} catch (NotFoundException $e) {
    // Recording not found (404)
} catch (RateLimitException $e) {
    // Too many requests (429)
    $retryAfter = $e->getRetryAfter();
} catch (ValidationException $e) {
    // Invalid parameters (400)
    $details = $e->getDetails();
} catch (ServerException $e) {
    // Server error (5xx)
} catch (PocketException $e) {
    // Any other API error
}
```

Note

The `RateLimitException` provides a `getRetryAfter()` method that returns the number of seconds you should wait before making another request.

Configuration Reference
-----------------------

[](#configuration-reference)

The following configuration options are available:

OptionEnvironment VariableDefaultDescription`api_key``POCKET_API_KEY`—Your Pocket API key`base_url``POCKET_BASE_URL``https://public.heypocketai.com`API base URL`api_version``POCKET_API_VERSION``v1`API version`timeout``POCKET_TIMEOUT``30`Request timeout in seconds`retry.times``POCKET_RETRY_TIMES``3`Number of retry attempts`retry.sleep``POCKET_RETRY_SLEEP``1000`Retry delay in milliseconds

Testing
-------

[](#testing)

To run the SDK's test suite:

```
composer test
```

Disclaimer
----------

[](#disclaimer)

This is an **unofficial** SDK for the Pocket API, developed and maintained by [Ryan Yannelli](https://ryanyannelli.com). It is not affiliated with, endorsed by, or officially connected to Pocket and Open Vision Engineering Inc any way. Use at your own risk. No warranties or guarantees are provided.

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 12.x or 13.x

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Credits
-------

[](#credits)

- [Ryan Yannelli](https://github.com/yannelli)
    - [Website](https://ryanyannelli.com)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance88

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Total

4

Last Release

60d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/53b64331d4de8c9cef47bc20707ed728c0e900cd2bda4ed7d95359ced8b9adf1?d=identicon)[yannelli](/maintainers/yannelli)

---

Top Contributors

[![yannelli](https://avatars.githubusercontent.com/u/59575788?v=4)](https://github.com/yannelli "yannelli (77 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (3 commits)")

---

Tags

apiapi-clientheypocketlaravellaravel-packagephppocketpocket-airecordingssdktranscriptionapilaravelsdkpocketTranscriptionrecordings

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/yannelli-pocket-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/yannelli-pocket-laravel/health.svg)](https://phpackages.com/packages/yannelli-pocket-laravel)
```

###  Alternatives

[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[njoguamos/laravel-plausible

A laravel package for interacting with plausible analytics api.

208.8k](/packages/njoguamos-laravel-plausible)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)