PichaFlow Flutter SDK (pichaflow_flutter)

Easily integrate the PichaFlow Engine into your Flutter applications. This package provides reactive UI widgets like PichaFlowUploadWidget for picking and uploading assets directly to the edge, including client-side optimization and secure handshake flows.

Installation

Add both pichaflow_flutter and the core pichaflow_dart SDK to your dependencies:

dependencies:
  flutter:
    sdk: flutter
  pichaflow_flutter: ^0.1.2
  pichaflow_dart: ^0.1.2

Quick Start

Create a client instance and pass it to the widget. The widget provides a default upload button or accepts a custom child widget.

import 'package:flutter/material.dart';
import 'package:pichaflow_flutter/pichaflow_flutter.dart';

class ProfileAvatarUpload extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Initialize PichaFlow client
    final client = PichaFlowClient(
      PichaFlowConfig(
        signatureUrl: 'https://your-supabase-project.supabase.co/functions/v1/pichaflow-upload',
      ),
    );

    return Scaffold(
      appBar: AppBar(title: const Text('Upload Avatar')),
      body: Center(
        child: PichaFlowUploadWidget(
          client: client,
          useSecure: true, // Recommended for client-side uploads
          tags: const ['avatar', 'user-profile'],
          onSuccess: (response) {
            print('Uploaded asset URL: ${response.url}');
          },
          onError: (error) {
            print('Upload error: $error');
          },
          onProgress: (progress) {
            print('Upload progress: ${progress.toStringAsFixed(1)}%');
          },
        ),
      ),
    );
  }
}

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.

Widget Parameters Reference

Property Type Required Description
client PichaFlowClient Yes The initialized client instance used to perform API/CDN calls.
useSecure bool No Default false. If true, fetches signature from backend route before uploading.
signatureUrl String? No Backend endpoint for signing secure upload requests.
customButton Widget? No Override the default blue button with your own custom widget.
mode UploadMode? No Internal upload mode flag.
tags List<String>? No Tags attached to the uploaded media for asset grouping/queries.
directory String? No Optional target folder path (e.g. avatars/user-123) to store uploaded assets.
tenantId String? No Tenant ID for separating files in multi-tenant environments.
customUploadEndpoint String? No Target upload URL, overriding the config default.

Callbacks

  • onSuccess: Function(UploadResponse) - Triggered when the upload successfully completes.
  • onError: Function(String) - Triggered on upload errors or cancellation.
  • onProgress: Function(double) - Reports current upload progress percentage.

Libraries

pichaflow_flutter