{"id":30093460,"url":"https://github.com/apillon/go-sdk","last_synced_at":"2025-08-09T09:42:08.748Z","repository":{"id":301321048,"uuid":"1001406273","full_name":"Apillon/go-sdk","owner":"Apillon","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-26T08:33:22.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-26T09:32:23.517Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Apillon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T10:22:01.000Z","updated_at":"2025-06-26T08:33:26.000Z","dependencies_parsed_at":"2025-06-26T09:34:46.794Z","dependency_job_id":"774a4f54-7985-48ec-8cd2-e75b14856309","html_url":"https://github.com/Apillon/go-sdk","commit_stats":null,"previous_names":["apillon/go-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Apillon/go-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apillon%2Fgo-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apillon%2Fgo-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apillon%2Fgo-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apillon%2Fgo-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Apillon","download_url":"https://codeload.github.com/Apillon/go-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Apillon%2Fgo-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269560041,"owners_count":24438179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-09T09:42:07.969Z","updated_at":"2025-08-09T09:42:08.732Z","avatar_url":"https://github.com/Apillon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apillon Go SDK\n\nA Go SDK for interacting with the [Apillon Storage API](https://wiki.apillon.io/build/2-storage-api.html). This SDK allows you to manage storage buckets, upload and manage files, and retrieve IPFS links programmatically.\n\nOriginally developed by [Leonardo Iara](https://github.com/LeonardoRyuta).\n\n## Features\n\n### Storage API\n- **Bucket Management:** Create, list, and retrieve storage buckets.\n- **File Upload:** Upload single or multiple files to a bucket.\n- **File Management:** List, retrieve details, and delete files.\n- **Directory Management:** Delete directories from a bucket.\n- **IPFS Integration:** Retrieve or generate IPFS links for files.\n- **IPFS Cluster Info:** Retrieve IPFS cluster information.\n\n### SDK features\n- **Session Management:** Manage upload sessions for batch file uploads.\n- **Context Support:** All operations support context for cancellation and timeouts.\n- **Robust Error Handling:** Comprehensive error types and detailed error messages.\n- **Automatic Retries:** Built-in retry mechanism for failed requests.\n- **Input Validation:** Thorough validation of all input parameters.\n\n## Requirements\n\n- Go 1.20 or higher\n- Apillon API key\n\n## Getting Started\n\nTo use the Apillon Storage Go SDK, you must register an account at [Apillon.io](https://apillon.io/), create a project, and generate an API key.\n\n## Installation\n\n```sh\ngo get github.com/Apillon/go-sdk\n```\n\n## Initialization\n\nImport the SDK in your Go code:\n\n```go\nimport (\n    \"context\"\n    \"github.com/Apillon/go-sdk/storage\"\n    \"github.com/Apillon/go-sdk/requests\"\n)\n```\n\nAll modules require the API key for authentication. You can provide it in two ways:\n\n### 1. Environment Variables\n\nSet the environment variable `APILLON_API_KEY` before running your application.\n\n**Windows (Command Prompt):**\n```sh\nset APILLON_API_KEY=your_api_key_here\n```\n\n**Linux/macOS:**\n```sh\nexport APILLON_API_KEY=your_api_key_here\n```\n\n### 2. Programatically\n\nYou can set the API key at runtime in your Go code:\n\n```go\nrequests.SetAPIKey(\"your_api_key_here\")\n```\n\n## Usage\n\n### Import the SDK\n\n```go\nimport (\n    \"github.com/Apillon/go-sdk/storage\"\n)\n```\n\n### Create a Bucket\n\n```go\nctx := context.Background()\nerr := storage.CreateBucket(ctx, \"my-bucket\", \"A description for my bucket\")\nif err != nil {\n    // handle error\n}\n```\n\n### List Buckets\n\n```go\nctx := context.Background()\nbuckets, err := storage.GetBucket(ctx, \"my-bucket\") // or storage.GetBucket(ctx, \"\") for all buckets\nif err != nil {\n    // handle error\n}\nfor _, bucket := range buckets.Data.Items {\n    fmt.Println(bucket.Name, bucket.BucketUUID)\n}\n```\n\n### Upload Files\n\n```go\nctx := context.Background()\nfiles := []storage.WholeFile{\n    {\n        Metadata: storage.FileMetadata{\n            FileName:    \"example.txt\",\n            ContentType: \"text/plain\",\n        },\n        Content: \"Hello, Apillon!\",\n    },\n}\n\nbucketUUID := \"your-bucket-uuid\"\nresult, err := storage.UploadFileProcess(ctx, bucketUUID, files)\nif err != nil {\n    // handle error\n}\nfmt.Println(\"Upload result:\", result)\n```\n\n### List Files in a Bucket\n\n```go\nctx := context.Background()\nfileList, err := storage.ListFilesInBucket(ctx, bucketUUID)\nif err != nil {\n    // handle error\n}\nfor _, file := range fileList.Data.Items {\n    fmt.Println(file.Name, file.FileUUID)\n}\n```\n\n### Get File Details\n\n```go\nctx := context.Background()\nfileDetails, err := storage.GetFileDetails(ctx, bucketUUID, fileUUID)\nif err != nil {\n    // handle error\n}\nfmt.Printf(\"File details: %+v\\n\", fileDetails.Data)\n```\n\n### Delete a File\n\n```go\nctx := context.Background()\n_, err := storage.DeleteFile(ctx, bucketUUID, fileUUID)\nif err != nil {\n    // handle error\n}\n```\n\n### Delete a Directory\n\n```go\nctx := context.Background()\nresp, err := storage.DeleteDirectory(ctx, bucketUUID, directoryUUID)\nif err != nil {\n    // handle error\n}\nfmt.Printf(\"Delete directory response: %+v\\n\", resp)\n```\n\n### Get or Generate IPFS Link\n\n```go\nctx := context.Background()\nipfsLink, err := storage.GetOrGenerateIPFSLink(ctx, cid)\nif err != nil {\n    // handle error\n}\nfmt.Println(\"IPFS Link:\", ipfsLink)\n```\n\n### Get IPFS Cluster Info\n\n```go\nctx := context.Background()\ninfo, err := storage.GetIPFSClusterInfo(ctx)\nif err != nil {\n    // handle error\n}\nfmt.Printf(\"IPFS Cluster Info: %+v\\n\", info.Data)\n```\n\n### Get Bucket Content\n\n```go\nctx := context.Background()\ncontent, err := storage.GetBucketContent(ctx, bucketUUID)\nif err != nil {\n    // handle error\n}\nfmt.Println(\"Bucket Content:\", content)\n```\n\n### Advanced: Manual Upload Session Control\n\n#### Start an Upload Session\n\n```go\nctx := context.Background()\nfiles := []storage.FileMetadata{\n    {FileName: \"file1.txt\", ContentType: \"text/plain\"},\n    {FileName: \"file2.json\", ContentType: \"application/json\"},\n}\nresp, err := storage.StartUploadFilesToBucket(ctx, bucketUUID, files)\nif err != nil {\n    // handle error\n}\nfmt.Println(\"Start upload session response:\", resp)\n```\n\n#### Upload File Content to Signed URL\n\n```go\nctx := context.Background()\nerr := storage.UploadFiles(ctx, signedURL, fileContent)\nif err != nil {\n    // handle error\n}\n```\n\n#### End an Upload Session\n\n```go\nctx := context.Background()\nresp, err := storage.EndSession(ctx, bucketUUID, sessionID)\nif err != nil {\n    // handle error\n}\nfmt.Println(\"End session response:\", resp)\n```\n\n## Error Handling\n\nThe SDK provides detailed error information through the `StorageError` type:\n\n```go\nif err != nil {\n    if storageErr, ok := err.(*storage.StorageError); ok {\n        fmt.Printf(\"Error Code: %d\\n\", storageErr.Code)\n        fmt.Printf(\"Error Message: %s\\n\", storageErr.Message)\n        if storageErr.Err != nil {\n            fmt.Printf(\"Original Error: %v\\n\", storageErr.Err)\n        }\n    }\n}\n```\n\nCommon error codes:\n- `ErrCodeInvalidInput` (40000001): Invalid input parameters\n- `ErrCodeDirectoryNotFound` (40406003): Directory not found\n- `ErrCodeDirectoryDeleting` (40006007): Directory already marked for deletion\n\n## Running Tests\n\nThe SDK includes comprehensive unit tests.\nTo run all tests:\n\n```sh\ngo test ./...\n```\n\n## Contributing\n\nPull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nMIT License\n\n## Notes\n\n- Ensure your API key is kept secure and **never** committed to version control.\n- For more details on the Apillon and the API, see the [API documentation](https://wiki.apillon.io/build/1-apillon-api.html).\n- The SDK supports context for better control over request lifecycle and cancellation.\n- All operations include automatic retries for failed requests.\n- Input validation is performed on all operations to ensure data integrity.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapillon%2Fgo-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapillon%2Fgo-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapillon%2Fgo-sdk/lists"}