docs: minimal examples on the readme

Author: alanshaw

README.md

@@ -14,7 +14,112 @@
 
 ### Examples
 
-TODO
+#### Principals
+
+See examples in [principals_test.go](./examples/principals_test.go)
+
+```go
+principal, err := did.Parse("did:key:z6MkfBSb2hC6g3UGnqNmWfmGvPdfMorBpT2osm9bk9b4Cyqu")
+fmt.Println("DID:", principal.DID())
+
+// generate a new ed25519 signer (it is also a principal - has a DID() method)
+signerPrincipal, err := ed25519.Generate()
+fmt.Println("DID:", signer.DID())
+
+// this principal can sign
+sig := signerPrincipal.Sign([]byte{1, 2, 3})
+fmt.Printf("Signature: 0x%x\n", sig)
+
+// and has a private key (use format utility to multibase base64pad encode)
+fmt.Println("Private Key:", signer.Format(signerPrincipal))
+
+// which can be stored and decoded later...
+signerPrincipal2, err := ed25519.Decode(signerPrincipal.Bytes())
+```
+
+#### Delegation
+
+See examples in [delegations_test.go](./examples/delegations_test.go)
+
+```go
+dlg, err = delegation.Delegate(
+  alice,           // issuer
+  bob,             // audience (receiver)
+  mailer,          // subject
+  "/message/send", // command
+  // policy (alice delegates bob capability to use the email service, but only
+  // allows bob to send to example.com email addresses)
+  delegation.WithPolicyBuilder(
+    policy.All(".to", policy.Like(".", "*.example.com")),
+  ),
+)
+```
+
+#### Invocation
+
+See examples in [invocations_test.go](./examples/invocations_test.go)
+
+```go
+inv, err := invocation.Invoke(
+  alice,
+  mailer,
+  "/message/send",
+  ipld.Map{
+    "from":    "alice@example.com",
+    "to":      "bob@example.com",
+    "message": "Hello Bob!",
+  },
+  invocation.WithProofs(dlg.Link()),
+)
+```
+
+#### Capability definition
+
+See examples in [capability_definition_test.go](./examples/capability_definition_test.go)
+
+```go
+type MessageSendArguments struct {
+	To      []string
+	Message string
+}
+
+messageSend, err := capability.New[*MessageSendArguments](
+  "/message/send",
+  capability.WithPolicyBuilder(
+    policy.NotEqual(".to", []string{}),
+  ),
+)
+
+// delegate the capability
+dlg, err := messageSend.Delegate(mailer, alice, mailer)
+
+// invoke the capability
+invocation, err := messageSend.Invoke(
+  alice,
+  mailer,
+  &MessageSendArguments{
+    To:      []string{"bob@example.com"},
+    Message: "Hello Bob, How do you do?",
+  },
+  invocation.WithProofs(dlg.Link()),
+)
+```
+
+#### Container
+
+See examples in [container_test.go](./examples/container_test.go)
+
+```go
+ct, err := container.New(
+  container.WithDelegations(dlg0, dlg1),
+  container.WithInvocations(inv0),
+  // container.WithReceipts(...),
+)
+
+// Various encoding options are available, the following (Base64Gzip) is good
+// for when you want to add the container to a HTTP header.
+buf, err := container.Encode(container.Base64Gzip, ct)
+```
 
 ## Contributing
 

examples/delegations_test.go

@@ -27,10 +27,10 @@ func TestDelegations(t *testing.T) {
 
 	// delegate alice capability to use the email service
 	_, err = delegation.Delegate(
-		mailer,
-		alice,
-		mailer,
-		"/message/send",
+		mailer,          // issuer
+		alice,           // audience (receiver)
+		mailer,          // subject
+		"/message/send", // command
 	)
 	if err != nil {
 		panic(err)

examples/invocations_test.go

@@ -0,0 +1,55 @@
+package examples
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/alanshaw/ucantone/ipld"
+	"github.com/alanshaw/ucantone/principal/ed25519"
+	"github.com/alanshaw/ucantone/ucan/delegation"
+	"github.com/alanshaw/ucantone/ucan/invocation"
+)
+
+func TestInvocations(t *testing.T) {
+	// mailer is an email service that can send emails
+	mailer, err := ed25519.Generate()
+	if err != nil {
+		panic(err)
+	}
+
+	alice, err := ed25519.Generate()
+	if err != nil {
+		panic(err)
+	}
+
+	// delegate alice capability to use the email service
+	dlg, err := delegation.Delegate(
+		mailer,          // issuer
+		alice,           // audience (receiver)
+		mailer,          // subject
+		"/message/send", // command
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	inv, err := invocation.Invoke(
+		alice,
+		mailer,
+		"/message/send",
+		ipld.Map{
+			"from":    "alice@example.com",
+			"to":      "bob@example.com",
+			"message": "Hello Bob!",
+		},
+		invocation.WithProofs(dlg.Link()),
+	)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(inv.Link())
+
+	// Now send the invocations to the mailer for execution. You'll need to also
+	// send the delegation as proof. You may want to use a _container_ for this.
+	// See `container_test.go` in this directory.
+}