From 662cd2123865af9fd3984b7b59b16fb277ae7b94 Mon Sep 17 00:00:00 2001
From: Patrick Dewey <p@pdewey.com>
Date: Tue, 9 Jun 2026 18:56:05 -0400
Subject: [PATCH] add basic examples and README

---
 README.md                    | 14 ++++++++++++
 examples/basic/main.go       | 43 ++++++++++++++++++++++++++++++++++++
 examples/create-card/main.go | 38 +++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+)
 create mode 100644 README.md
 create mode 100644 examples/basic/main.go
 create mode 100644 examples/create-card/main.go

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a25c086
--- /dev/null
+++ b/README.md
@@ -0,0 +1,14 @@
+# Semble
+
+A Go client library for the [Semple API](https://docs.cosmik.network/semble-api)
+
+## Installation
+
+```sh
+go get tangled.org/pdewey.com/semble@latest
+```
+
+## Usage
+
+See [pkg.go.dev/tangled.org/pdewey.com/semble](https://pkg.go.dev/tangled.org/pdewey.com/semble),
+or check out the [examples](./examples/)
diff --git a/examples/basic/main.go b/examples/basic/main.go
new file mode 100644
index 0000000..fca7d5c
--- /dev/null
+++ b/examples/basic/main.go
@@ -0,0 +1,43 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	semble "tangled.org/pdewey.com/semble"
+)
+
+func main() {
+	ctx := context.Background()
+
+	client, err := semble.New(semble.WithAPIKey(os.Getenv("SEMBLE_API_KEY")))
+	if err != nil {
+		log.Fatalf("create client: %v", err)
+	}
+
+	profile, err := client.GetMyProfile(ctx, true)
+	if err != nil {
+		log.Fatalf("get profile: %v", err)
+	}
+	fmt.Printf("signed in as @%s (%s)\n", profile.Handle, profile.Name)
+
+	cards, err := client.ListMyURLCards(ctx, semble.CardListQuery{
+		PageQuery: semble.PageQuery{Page: 1, Limit: 5},
+	})
+	if err != nil {
+		log.Fatalf("list cards: %v", err)
+	}
+
+	fmt.Printf("showing up to %d cards\n", len(cards.Cards))
+	for _, card := range cards.Cards {
+		title := card.URL
+		if metadata, ok := card.CardContent.(map[string]any); ok {
+			if value, ok := metadata["title"].(string); ok && value != "" {
+				title = value
+			}
+		}
+		fmt.Printf("- %s\n  %s\n", title, card.URL)
+	}
+}
diff --git a/examples/create-card/main.go b/examples/create-card/main.go
new file mode 100644
index 0000000..f1fbfc8
--- /dev/null
+++ b/examples/create-card/main.go
@@ -0,0 +1,38 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	semble "tangled.org/pdewey.com/semble"
+)
+
+func main() {
+	apiKey := os.Getenv("SEMBLE_API_KEY")
+	if apiKey == "" {
+		log.Fatal("set SEMBLE_API_KEY")
+	}
+
+	ctx := context.Background()
+	client, err := semble.New(semble.WithAPIKey(apiKey))
+	if err != nil {
+		log.Fatalf("create client: %v", err)
+	}
+
+	url := "https://tangled.org/pdewey.com/semble"
+
+	created, err := client.AddURLToLibrary(ctx, semble.AddURLRequest{
+		URL:  url,
+		Note: "Go client library for the Semble API.",
+	})
+	if err != nil {
+		log.Fatalf("create card: %v", err)
+	}
+
+	fmt.Printf("created URL card: %s\n", created.URLCardID)
+	if created.NoteCardID != "" {
+		fmt.Printf("created note card: %s\n", created.NoteCardID)
+	}
+}
-- 
2.54.0