icpaybucket

README

icpay-bucket

Full Go client for ICPay Bucket.

go get github.com/icpay/icpay-bucket

See docs/pkg/go/README.md for the complete API reference.

Quick start

client, _ := icpaybucket.NewClient(icpaybucket.ClientOptions{APIKey: "icp_cloud_…"})
client.UploadFile("icp", "/hello.txt", []byte("hello\n"), "text/plain", "")
fmt.Println(client.PublicURL("icp", "/hello.txt"))

v1.1.0 — file API + bulk + chunked upload

Methods live in files.go. Bucket admin and API key methods use the canister actor directly until wrapped.

License

MIT

Documentation

Overview

Package icpaybucket is a client for the ICPay Bucket canister.

Index

• Constants
• func PublicFileURL(canisterID, bucketName, path string) string
• type ApiKeyPermissions
• type ApiResult
• type Client
  • func NewClient(options ClientOptions) (*Client, error)
  • func (c *Client) BeginFileUpload(bucketID, path, contentType string, totalSize uint64, apiKey string) (resultFileID, error)
  • func (c *Client) BulkCopyFiles(bucketID string, ops []FilePathOp, apiKey string) (resultNat, error)
  • func (c *Client) BulkDeleteFiles(bucketID string, paths []string, apiKey string) (resultNat, error)
  • func (c *Client) BulkMoveFiles(bucketID string, ops []FilePathOp, apiKey string) (resultNat, error)
  • func (c *Client) CompleteFileUpload(uploadID, apiKey string) (resultFileID, error)
  • func (c *Client) CopyFile(bucketID, source, destination, apiKey string) (resultFilePublic, error)
  • func (c *Client) DeleteFile(bucketID, path, apiKey string) (resultUnit, error)
  • func (c *Client) DownloadFile(bucketID, path, apiKey string) (resultBlob, error)
  • func (c *Client) FileExists(bucketID, path, apiKey string) (resultBool, error)
  • func (c *Client) GetBucketCycleStatus() (..., error)
  • func (c *Client) GetFile(bucketID, path, apiKey string) (resultFilePublic, error)
  • func (c *Client) GetFileMetadata(bucketID, path, apiKey string) (resultString, error)
  • func (c *Client) GetPublicFileURL(bucketID, path string) (resultString, error)
  • func (c *Client) ListFiles(bucketID string, page, pageSize uint64, apiKey string) (resultFileList, error)
  • func (c *Client) ListFolder(bucketID, prefix string, page, pageSize uint64, apiKey string) (resultFileList, error)
  • func (c *Client) MoveFile(bucketID, source, destination, apiKey string) (resultFilePublic, error)
  • func (c *Client) PublicURL(bucketName, path string) string
  • func (c *Client) SearchFiles(bucketID, query string, page, pageSize uint64, apiKey string) (resultFileList, error)
  • func (c *Client) SetFileMetadata(bucketID, path, metadata, apiKey string) (resultFilePublic, error)
  • func (c *Client) SetFileTags(bucketID, path string, tags []string, apiKey string) (resultFilePublic, error)
  • func (c *Client) UploadFile(bucketID, path string, data []byte, contentType, apiKey string) (resultFileID, error)
  • func (c *Client) UploadFileChunkIndexed(uploadID string, chunkIndex uint64, data []byte) (resultNat, error)
• type ClientOptions
• type FileListPage
• type FilePathOp
• type FilePublic

Constants

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

const SingleMaxBytes = 1_850_000

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 ApiKeyPermissions

type ApiKeyPermissions struct {
	Read   bool `ic:"read"`
	Write  bool `ic:"write"`
	Delete bool `ic:"delete"`
}

type ApiResult

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

type Client

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

func NewClient

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

func (*Client) BeginFileUpload

func (c *Client) BeginFileUpload(bucketID, path, contentType string, totalSize uint64, apiKey string) (resultFileID, error)

func (*Client) BulkCopyFiles

func (c *Client) BulkCopyFiles(bucketID string, ops []FilePathOp, apiKey string) (resultNat, error)

func (*Client) BulkDeleteFiles

func (c *Client) BulkDeleteFiles(bucketID string, paths []string, apiKey string) (resultNat, error)

func (*Client) BulkMoveFiles

func (c *Client) BulkMoveFiles(bucketID string, ops []FilePathOp, apiKey string) (resultNat, error)

func (*Client) CompleteFileUpload

func (c *Client) CompleteFileUpload(uploadID, apiKey string) (resultFileID, error)

func (*Client) CopyFile

func (c *Client) CopyFile(bucketID, source, destination, apiKey string) (resultFilePublic, error)

func (*Client) DeleteFile

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

func (*Client) DownloadFile

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

func (*Client) FileExists

func (c *Client) FileExists(bucketID, path, apiKey string) (resultBool, error)

func (*Client) GetBucketCycleStatus

func (c *Client) GetBucketCycleStatus() (ApiResult[struct {
	Balance                idl.Nat `ic:"balance"`
	Status                 string  `ic:"status"`
	CanAcceptNewBuckets    bool    `ic:"canAcceptNewBuckets"`
	EstimatedDaysRemaining idl.Nat `ic:"estimatedDaysRemaining"`
	DailyBurn              idl.Nat `ic:"dailyBurn"`
}], error)

func (*Client) GetFile

func (c *Client) GetFile(bucketID, path, apiKey string) (resultFilePublic, error)

func (*Client) GetFileMetadata

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

func (*Client) GetPublicFileURL

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

func (*Client) ListFiles

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

func (*Client) ListFolder

func (c *Client) ListFolder(bucketID, prefix string, page, pageSize uint64, apiKey string) (resultFileList, error)

func (*Client) MoveFile

func (c *Client) MoveFile(bucketID, source, destination, apiKey string) (resultFilePublic, error)

func (*Client) PublicURL

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

func (*Client) SearchFiles

func (c *Client) SearchFiles(bucketID, query string, page, pageSize uint64, apiKey string) (resultFileList, error)

func (*Client) SetFileMetadata

func (c *Client) SetFileMetadata(bucketID, path, metadata, apiKey string) (resultFilePublic, error)

func (*Client) SetFileTags

func (c *Client) SetFileTags(bucketID, path string, tags []string, apiKey string) (resultFilePublic, error)

func (*Client) UploadFile

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

func (*Client) UploadFileChunkIndexed

func (c *Client) UploadFileChunkIndexed(uploadID string, chunkIndex uint64, data []byte) (resultNat, error)

type ClientOptions

type ClientOptions struct {
	APIKey     string
	CanisterID string
	Host       string
	Identity   identity.Identity
}

type FileListPage

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

type FilePathOp

type FilePathOp struct {
	Source      string `ic:"source"`
	Destination string `ic:"destination"`
}

type FilePublic

type FilePublic struct {
	ID          string   `ic:"id"`
	Path        string   `ic:"path"`
	Name        string   `ic:"name"`
	Size        idl.Nat  `ic:"size"`
	ContentType string   `ic:"contentType"`
	CreatedAt   idl.Int  `ic:"createdAt"`
	UpdatedAt   *idl.Int `ic:"updatedAt"`
	Metadata    *string  `ic:"metadata"`
	Tags        []string `ic:"tags"`
	PublicURL   *string  `ic:"publicUrl"`
}