icpaybucket

README

icpay-bucket

Minimal Go client for ICPay Bucket — on-chain encrypted file storage on the Internet Computer.

go get github.com/prasangapokharel/icpay-bucket-go

Quick start

package main

import (
	"fmt"

	icpaybucket "github.com/prasangapokharel/icpay-bucket-go"
)

func main() {
	client, err := icpaybucket.NewClient(icpaybucket.ClientOptions{
		APIKey: "icp_cloud_…", // authorizes writes
	})
	if err != nil {
		panic(err)
	}

	// Upload (single call, files up to ~1.85 MB)
	up, err := client.UploadFile("icp", "/logo.webp", data, "image/webp", "")
	if err != nil || up.Err != nil {
		panic(err)
	}
	fmt.Println("uploaded:", *up.Ok)

	// Public CDN URL — no call needed
	url := client.PublicURL("icp", "/logo.webp")

	// List files
	list, err := client.ListFiles("icp", 0, 20)
	if err != nil || list.Err != nil {
		panic(err)
	}
	for _, f := range list.Ok.Items {
		fmt.Println(f.Path)
	}

	// Delete with the API key
	del, err := client.DeleteFile("icp", "/logo.webp", "")
	if err != nil || del.Err != nil {
		panic(err)
	}
}

API

• UploadFile(bucketID, path, data, contentType, apiKey) → { Ok } | { Err }.
• DeleteFile(bucketID, path, apiKey) → { Ok } | { Err }.
• ListFiles(bucketID, page, pageSize) → paginated file list.
• DownloadFile(bucketID, path) → file bytes (public + private buckets).
• GetPublicFileURL(bucketID, path) → canister-provided CDN URL.
• PublicURL(bucketName, path) — CDN URL computed locally (no call).
• PublicFileURL(canisterID, bucketName, path) — same, standalone.

Writes are authorized by a bucket API key or an Internet Identity. Reads on public buckets work for any caller.

Note: DownloadFile takes the bucket id, not the bucket name. Other endpoints (UploadFile, DeleteFile, ListFiles, GetPublicFileURL) accept the bucket name (e.g. "icp"). To download, resolve the id first via the canister's getBucket(name) query.

License

MIT

Documentation

Overview

Package icpaybucket is a minimal client for the ICPay Bucket canister — on-chain encrypted file storage on the Internet Computer.

Index

• Constants
• func PublicFileURL(canisterID, bucketName, path string) string
• type ApiResult
• type Client
  • func NewClient(options ClientOptions) (*Client, error)
  • func (c *Client) DeleteFile(bucketID, path, apiKey string) (resultUnit, error)
  • func (c *Client) DownloadFile(bucketID, path string) (resultBlob, error)
  • func (c *Client) GetPublicFileURL(bucketID, path string) (resultString, error)
  • func (c *Client) ListFiles(bucketID string, page, pageSize uint64) (resultFileList, error)
  • func (c *Client) PublicURL(bucketName, path string) string
  • func (c *Client) UploadFile(bucketID, path string, data []byte, contentType string, apiKey string) (resultFileID, error)
• type ClientOptions
• type FileListPage
• type FilePublic

Constants

const DefaultCanisterID = "6vbhm-nqaaa-aaaan-q6muq-cai"

DefaultCanisterID is the live ICPay backend canister on mainnet.

const SingleMaxBytes = 1_850_000

SingleMaxBytes is the ceiling for a single uploadFile call (~1.85 MB).

Functions

func PublicFileURL

func PublicFileURL(canisterID, bucketName, path string) string

PublicFileURL builds the raw HTTP gateway URL for a public file. No canister call is involved — this is the URL served directly by the gateway.

Types

type ApiResult

type ApiResult[T any] struct {
	Ok  *T      `ic:"ok,variant"`
	Err *string `ic:"err,variant"`
}

ApiResult is a canister variant { ok: T } | { err: Text }.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the ICPay bucket canister.

Writes (upload/delete) are authorized by a bucket API key or by an Internet Identity. Reads (list/download/publicUrl) work for any caller on a public bucket.

func NewClient

func NewClient(options ClientOptions) (*Client, error)

NewClient creates a Client. An anonymous caller is used unless an identity is supplied; the API key (when set) authorizes writes as the bucket owner.

func (*Client) DeleteFile

func (c *Client) DeleteFile(bucketID, path, apiKey string) (resultUnit, error)

DeleteFile removes a file. Authorized by the API key.

func (*Client) DownloadFile

func (c *Client) DownloadFile(bucketID, path string) (resultBlob, error)

DownloadFile returns file bytes (public + private buckets).

func (*Client) GetPublicFileURL

func (c *Client) GetPublicFileURL(bucketID, path string) (resultString, error)

GetPublicFileURL returns the canister-provided CDN URL for a file.

func (*Client) ListFiles

func (c *Client) ListFiles(bucketID string, page, pageSize uint64) (resultFileList, error)

ListFiles returns a paginated file list for a bucket. Public buckets allow any caller.

func (*Client) PublicURL

func (c *Client) PublicURL(bucketName, path string) string

PublicURL builds the CDN URL locally — no canister call.

func (*Client) UploadFile

func (c *Client) UploadFile(bucketID, path string, data []byte, contentType string, apiKey string) (resultFileID, error)

UploadFile stores a file in a single call (up to ~1.85 MB).

type ClientOptions

type ClientOptions struct {
	// APIKey authorizes writes without an identity.
	APIKey string
	// CanisterID overrides the default ICPay canister.
	CanisterID string
	// Host overrides the IC host (default https://icp0.io, mainnet).
	Host string
	// Identity overrides the anonymous caller used for updates.
	Identity identity.Identity
}

ClientOptions configures a Client.

type FileListPage

type FileListPage struct {
	Items    []FilePublic `ic:"items"`
	Total    idl.Nat      `ic:"total"`
	Page     idl.Nat      `ic:"page"`
	PageSize idl.Nat      `ic:"pageSize"`
}

FileListPage is the canister FileListPage record.

type FilePublic

type FilePublic struct {
	ID          string  `ic:"id"`
	Path        string  `ic:"path"`
	Size        idl.Nat `ic:"size"`
	ContentType string  `ic:"contentType"`
	CreatedAt   idl.Int `ic:"createdAt"`
	PublicURL   *string `ic:"publicUrl"`
}

FilePublic is the canister FilePublic record.