{"id":41098750,"url":"https://github.com/epheo/anytype-go","last_synced_at":"2026-01-22T15:01:48.356Z","repository":{"id":288421172,"uuid":"968031743","full_name":"epheo/anytype-go","owner":"epheo","description":"A Go SDK for interacting with the Anytype API to manage spaces, objects, and perform searches. This library provides a feature-rich, fluent interface to integrate Anytype functionality into your Go applications.","archived":false,"fork":false,"pushed_at":"2025-06-17T01:25:25.000Z","size":7927,"stargazers_count":9,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-01T00:30:55.166Z","etag":null,"topics":["anytype","golang","sdk"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epheo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-04-17T11:48:49.000Z","updated_at":"2025-07-23T20:07:45.000Z","dependencies_parsed_at":"2025-05-13T12:40:11.243Z","dependency_job_id":null,"html_url":"https://github.com/epheo/anytype-go","commit_stats":null,"previous_names":["epheo/anytype-go"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/epheo/anytype-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epheo%2Fanytype-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epheo%2Fanytype-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epheo%2Fanytype-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epheo%2Fanytype-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epheo","download_url":"https://codeload.github.com/epheo/anytype-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epheo%2Fanytype-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28664832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T14:01:31.714Z","status":"ssl_error","status_checked_at":"2026-01-22T13:59:23.143Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["anytype","golang","sdk"],"created_at":"2026-01-22T15:01:35.807Z","updated_at":"2026-01-22T15:01:48.346Z","avatar_url":"https://github.com/epheo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Anytype-Go SDK\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/epheo/anytype-go)](https://goreportcard.com/report/github.com/epheo/anytype-go)\n[![GoDoc](https://godoc.org/github.com/epheo/anytype-go?status.svg)](https://godoc.org/github.com/epheo/anytype-go)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nA Go SDK for interacting with the [Anytype](https://anytype.io) API to manage spaces, objects, and perform searches. This library provides a feature-rich, fluent interface to integrate Anytype functionality into your Go applications.\n\n## Table of Contents\n\n- [📋 Overview](#-overview)\n- [🔄 API Version Support](#-api-version-support)\n- [📥 Installation](#-installation)\n- [🚦 Quick Start](#-quick-start)\n  - [Authentication](#authentication)\n  - [Working with Spaces](#working-with-spaces)\n  - [Working with Objects](#working-with-objects)\n  - [Searching](#searching)\n- [🔧 Advanced Examples](#-advanced-examples)\n  - [Working with Object Types and Templates](#working-with-object-types-and-templates)\n  - [Managing Object Properties](#managing-object-properties)\n  - [Working with Lists and Views](#working-with-lists-and-views)\n- [💡 Design Philosophy](#-design-philosophy)\n  - [1. Fluent Interface Pattern](#1-fluent-interface-pattern)\n  - [2. Domain-Driven Design](#2-domain-driven-design)\n  - [3. Naming Convention](#3-naming-convention)\n  - [4. Middleware Architecture](#4-middleware-architecture)\n- [📚 API Reference](#-api-reference)\n- [✅ Best Practices](#-best-practices)\n- [🔧 Troubleshooting](#-troubleshooting)\n- [🧪 Testing](#-testing)\n  - [Unit Tests with Mocks](#unit-tests-with-mocks)\n  - [API Coverage Tests](#api-coverage-tests)\n- [👥 Contributing](#-contributing)\n- [📜 License](#-license)\n\n## 📋 Overview\n\nAnytype-Go provides a Go SDK for interacting with Anytype's local API. This SDK offers a clean, fluent interface for:\n\n- Managing spaces and their members\n- Creating, reading, updating, and deleting objects\n- Searching for objects using various filters\n- Exporting objects to different formats\n- Working with object types, templates, and properties\n\n## 🔄 API Version Support\n\nThis SDK is compatible with Anytype API version `2025-04-22`. The SDK follows Anytype's API versioning scheme, which uses date-based versioning for stability and compatibility:\n\n- All API requests include the `Anytype-Version` header set to `2025-04-22`\n- Type keys such as `page` and `collection` follow the latest API specification\n- Authentication uses the app key Bearer token method\n\nIf you encounter any compatibility issues when Anytype updates its API, please check for an updated version of this SDK that supports the new API version.\n\n## 📥 Installation\n\n```bash\ngo get github.com/epheo/anytype-go\n```\n\nImport both the main package and client implementation:\n\n```go\nimport (\n    \"github.com/epheo/anytype-go\"\n    _ \"github.com/epheo/anytype-go/client\" // Register client implementation\n)\n```\n\n## 🚦 Quick Start\n\n\u003e 📁 **More complete examples** can be found in the [examples](./examples) directory, including full implementations of authentication, working with spaces, objects, and more.\n\n### Authentication\n\nTo use the Anytype API, you need to obtain an AppKey. Here's how to get it:\n\n```go\n// Step 1: Initiate authentication and get challenge ID\nauthResponse, err := client.Auth().DisplayCode(ctx, \"MyAnytypeApp\")\nif err != nil {\n    log.Fatalf(\"Failed to initiate authentication: %v\", err)\n}\nchallengeID := authResponse.ChallengeID\n\n// Step 2: User needs to enter the code shown in Anytype app\nfmt.Println(\"Please enter the authentication code shown in Anytype:\")\nvar code string\nfmt.Scanln(\u0026code)\n\n// Step 3: Complete authentication and get tokens\ntokenResponse, err := client.Auth().GetToken(ctx, challengeID, code)\nif err != nil {\n    log.Fatalf(\"Authentication failed: %v\", err)\n}\n\n// Now you have your authentication token\nappKey := tokenResponse.AppKey\n\n// Create authenticated client\nclient := anytype.NewClient(\n    anytype.WithBaseURL(\"http://localhost:31009\"), // Default Anytype local API URL\n    anytype.WithAppKey(appKey),\n)\n```\n\n\u003e **Note**: The authentication flow requires user interaction. When you call `DisplayCode`, Anytype will show a verification code that must be entered in your application.\n\n### Working with Spaces\n\n```go\n// List all spaces\nspaces, err := client.Spaces().List(ctx)\n\n// Get a specific space\nspace, err := client.Space(spaceID).Get(ctx)\n\n// Create a new space\nnewSpace, err := client.Spaces().Create(ctx, anytype.CreateSpaceRequest{\n    Name:        \"My New Workspace\",\n    Description: \"Created via the Go SDK\",\n})\n```\n\n### Working with Objects\n\n```go\n// Get an object\nobject, err := client.Space(spaceID).Object(objectID).Get(ctx)\n\n// Delete an object\nerr = client.Space(spaceID).Object(objectID).Delete(ctx)\n\n// Export an object to markdown\nexportResult, err := client.Space(spaceID).Object(objectID).Export(ctx, \"markdown\")\n\n// Create a new object\nnewObject, err := client.Space(spaceID).Objects().Create(ctx, anytype.CreateObjectRequest{\n    TypeKey:     \"page\",\n    Name:        \"My New Page\",\n    Description: \"Created via the Go SDK\",\n    Body:        \"# This is a new page\\n\\nWith some content in markdown format.\",\n    Icon: \u0026anytype.Icon{\n        Format: anytype.IconFormatEmoji,\n        Emoji: \"📄\",\n    },\n})\n```\n\n### Searching\n\n```go\n// Search within a specific space\nresults, err := client.Space(spaceID).Search(ctx, anytype.SearchRequest{\n    Query: \"important notes\",\n    Sort: \u0026anytype.SortOptions{\n        Property:  anytype.SortPropertyLastModifiedDate,\n        Direction: anytype.SortDirectionDesc,\n    },\n    Types: []string{\"note\", \"page\"}, // Filter by specific types\n})\n```\n\n## 🔧 Advanced Examples\n\n### Working with Object Types and Templates\n\n```go\n// List available object types in a space\nobjectTypes, err := client.Space(spaceID).Types().List(ctx)\n\n// Get details of a specific object type\ntypeDetails, err := client.Space(spaceID).Type(typeKey).Get(ctx)\n\n// List templates for a specific object type\ntemplates, err := client.Space(spaceID).Type(typeKey).Templates().List(ctx)\n\n// Get details of a specific template\ntemplate, err := client.Space(spaceID).Type(typeKey).Template(templateID).Get(ctx)\n```\n\n### Managing Object Properties\n\n```go\n// Update object properties\nerr := client.Space(spaceID).Object(objectID).UpdateProperties(ctx, anytype.UpdatePropertiesRequest{\n    Properties: map[string]interface{}{\n        \"name\":        \"Updated Title\",\n        \"description\": \"Updated description\",\n        \"status\":      \"In Progress\",\n        \"priority\":    \"High\",\n        \"deadline\":    time.Now().AddDate(0, 0, 14).Format(time.RFC3339),\n    },\n})\n\n// Add a relation to another object\nerr := client.Space(spaceID).Object(objectID).AddRelation(ctx, relatedObjectID, \"related-to\")\n```\n\n### Working with Lists and Views\n\n```go\n// Create a new list to organize objects\nnewList, err := client.Space(spaceID).Lists().Create(ctx, anytype.CreateListRequest{\n    Name:        \"Project Tasks\",\n    Description: \"All tasks for our current project\",\n    Icon: \u0026anytype.Icon{\n        Type:  \"emoji\",\n        Value: \"📝\",\n    },\n})\n\n// Add objects to a list\nerr := client.Space(spaceID).List(listID).AddObjects(ctx, []string{objectID1, objectID2})\n\n// Create a custom view for a list\nnewView, err := client.Space(spaceID).List(listID).Views().Create(ctx, anytype.CreateViewRequest{\n    Name: \"Priority View\",\n    Type: \"board\",\n    GroupBy: []string{\"priority\"},\n    SortBy: []anytype.SortOptions{\n        {\n            Property:  \"deadline\",\n            Direction: anytype.SortDirectionAsc,\n        },\n    },\n    Filters: []anytype.FilterCondition{\n        {\n            Property: \"status\",\n            Operator: anytype.OperatorNotEquals,\n            Value:    \"Completed\",\n        },\n    },\n})\n```\n\n## 💡 Design Philosophy\n\nThe Anytype-Go SDK is built around three core design principles:\n\n### 1. Fluent Interface Pattern\n\n```go\nexportedMarkdown, err := client.\n    Space(spaceID).\n    Object(objectID).\n    Export(ctx, \"markdown\")\n```\n\n**Benefits:**\n\n- Readable code that mirrors natural language\n- IDE autocomplete reveals available operations\n- Compile-time type safety\n- Reduced boilerplate code\n\n### 2. Domain-Driven Design\n\nThe SDK is organized around Anytype's core concepts (spaces, objects, types) with interfaces that map directly to these concepts:\n\n- `SpaceClient` and `SpaceContext` for spaces\n- `ObjectClient` and `ObjectContext` for objects\n- `TypeClient` for object types\n- `ListClient` for lists and views\n\n### 3. Naming Convention\n\nThe naming of interfaces and types in this library follows a clear and consistent pattern to improve code readability and API fluency:\n\n- **`\u003cEntity\u003eClient`**: Represents a client that operates on collections of entities (e.g., `SpaceClient` for working with multiple spaces, `TypeClient` for working with multiple object types). These clients handle operations like listing, searching, and creating new entities.\n- **`\u003cEntity\u003eContext`**: Represents a client that operates on a single, specific entity instance (e.g., `SpaceContext` for a single space, `ObjectContext` for a single object). These handle operations like getting details, updating, or deleting a specific entity.\n\nThis naming convention creates a fluent, chainable API where:\n\n1. Collection operations use the `\u003cEntity\u003eClient` pattern (e.g., `client.Spaces().List()`)\n2. Instance operations use the `\u003cEntity\u003eContext` pattern (e.g., `client.Space(spaceID).Get()`)\n3. Nested resources follow a natural hierarchy (e.g., `client.Space(spaceID).Object(objectID).Export()`)\n\nThis design enables intuitive navigation through the API that mirrors natural language and domain concepts.\n\n### 4. Middleware Architecture\n\n```text\nHTTP Request → ValidationMiddleware → RetryMiddleware → DisconnectMiddleware → HTTP Client → API\n```\n\nEach middleware handles a specific concern:\n\n- **Validation**: Validates requests before sending\n- **Retry**: Handles transient errors with configurable policies\n- **Disconnect**: Manages network interruptions\n\n## 📚 API Reference\n\nFor detailed API documentation, see [GoDoc](https://godoc.org/github.com/epheo/anytype-go).\n\n## ✅ Best Practices\n\n1. **Reuse the client instance** across your application\n2. **Use context for cancellation** to control timeouts\n3. **Handle rate limiting** with appropriate backoff strategies\n4. **Validate inputs** before making API calls\n5. **Check for errors** and handle them appropriately\n6. **Use the fluent interface** for cleaner, more readable code\n\n## 🔧 Troubleshooting\n\n- **Authentication Failures**: Verify your app key\n- **Connection Issues**: Ensure Anytype is running locally\n- **Rate Limiting**: Implement backoff if making many requests\n- **API Version Mismatch**: If you get errors about unknown fields or unexpected responses, check that your Anytype app version is compatible with the API version this SDK supports (2025-04-22)\n\n## 🧪 Testing\n\nThe SDK testing approach focuses on behavior verification using mock implementations:\n\n### Unit Tests with Mocks\n\n`tests`: Tests ensure that client interfaces behave according to specifications using mock implementations to simulate API responses.\n\n```bash\ngo test -v ./tests/...\n```\n\n### API Coverage Tests\n\n`tests_api_coverage`: Tests verify that all API endpoints are properly defined and can be called with appropriate parameters.\n\n```bash\ngo test -v ./tests_api_coverage/...\n```\n\nThe test infrastructure uses mock implementations (in `tests/mocks`) to simulate the Anytype API, allowing thorough testing without requiring a running Anytype instance.\n\n## 👥 Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a new Pull Request\n\n## 📜 License\n\nApache License 2.0 - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepheo%2Fanytype-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepheo%2Fanytype-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepheo%2Fanytype-go/lists"}