pichaflow_dart 0.1.3

PichaFlow core Dart SDK. Provides zero-egress CDN URL generation, secure signature handshakes, on-device image optimization, and programmatic asset management.

PichaFlow Dart SDK (pichaflow_dart)

The core Dart SDK for the PichaFlow Engine, an edge-native media orchestration service. This package provides the foundational PichaFlowClient for communicating with the PichaFlow API, uploading assets, generating delivery URLs, and deleting media files.

Installation

Add pichaflow_dart to your pubspec.yaml:

dependencies:
  pichaflow_dart: ^0.1.2

---

Direct Direct-to-Edge Uploads

If your environment is secure (e.g., server-side Dart, CLI tool, or test environment), you can initialize the client using your secret/API key directly:

import 'package:pichaflow_dart/pichaflow_dart.dart';

void main() async {
  final client = PichaFlowClient(
    PichaFlowConfig(
      apiKey: 'sk_live_your_secret_key',
    ),
  );

  final List<int> fileBytes = [/* raw image/file bytes */];

  try {
    final response = await client.upload(
      fileBytes,
      'avatar.jpg',
      options: UploadOptions(
        tags: ['user-avatar'],
      ),
    );
    print('Uploaded! ID: ${response.id}, URL: ${response.url}');
  } catch (e) {
    print('Failed: $e');
  }
}

---

Secure Handshake Uploads (HMAC Proxy)

When running inside client applications (like Flutter mobile or web apps), never expose your PichaFlow Secret Key (sk_live_...).

Instead, use the secure HMAC handshake flow:

1. Provide a signatureUrl pointing to your backend signing endpoint.
2. Call secureUpload(). The client fetches a temporary upload token from your signing backend and uploads the file directly to PichaFlow.

final client = PichaFlowClient(
  PichaFlowConfig(
    signatureUrl: 'https://your-api.com/v1/pichaflow-upload', // Signing endpoint
  ),
);

final response = await client.secureUpload(
  fileBytes,
  'photo.png',
  options: UploadOptions(directory: 'photos'),
);

Caution

Authentication Check Required: You must secure your backend signatureUrl endpoint with appropriate session or token authentication middleware. If this route is left public and unauthenticated, any user or bot can request valid signatures to upload files directly to your account, risking billing spikes or bucket abuse.

Your backend signing endpoint must forward the security constraint headers (x-picha-max-size, x-picha-allowed-types, and x-picha-directory) received from the client.

Implementing the Secure Signing Backend

Below is a complete Deno / Supabase Edge Function implementation for the signing endpoint:

import { serve } from "https://deno.land/std@0.168.0/http/server.ts"

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, x-picha-max-size, x-picha-allowed-types, x-picha-directory',
}

serve(async (req: Request) => {
  // CORS Preflight
  if (req.method === 'OPTIONS') {
    return new Response('ok', { headers: corsHeaders })
  }

  try {
    const pichaFlowKey = Deno.env.get('PICHAFLOW_SECRET_KEY')
    if (!pichaFlowKey) {
      throw new Error('Server configuration error: Missing PICHAFLOW_SECRET_KEY')
    }

    const body = await req.json().catch(() => ({}))

    // Call PichaFlow Management API to generate a signed upload token,
    // forwarding the size, types, and directory restrictions sent by the client.
    const response = await fetch('https://api.pichaflow.com/v1/upload/sign', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${pichaFlowKey}`,
        'Content-Type': 'application/json',
        'x-picha-max-size': req.headers.get('x-picha-max-size') || '',
        'x-picha-allowed-types': req.headers.get('x-picha-allowed-types') || '',
        'x-picha-directory': req.headers.get('x-picha-directory') || '',
      },
      body: JSON.stringify({
        tenantId: body?.tenantId
      })
    })

    const data = await response.json()

    return new Response(JSON.stringify(data), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: response.status
    })
  } catch (err: any) {
    return new Response(JSON.stringify({ error: err.message }), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
      status: 500
    })
  }
})

Delivery URLs

Generate optimized CDN URLs with presets and resize transformations:

final url = client.getDeliveryUrl(
  'users-photos/avatar.jpg',
  w: 300,
  h: 300,
  q: 85,
  f: 'webp',
);