documentation updates

Author: slingamn

.gitignore

@@ -2,3 +2,5 @@ vendor/**
 
 .DS_Store
 *.out
+
+*.swp

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+All notable changes to webpush-go will be documented in this file.
+
+## [2.0.0] - 2025-01-01
+
+* Update the `Keys` struct definition to store `Auth` as `[16]byte` and `P256dh` as `*ecdh.PublicKey`
+    * `Keys` can no longer be compared with `==`; use `(*Keys.Equal)` instead
+    * The JSON representation has not changed and is backwards and forwards compatible with v1
+    * `DecodeSubscriptionKeys` is a helper to decode base64-encoded auth and p256dh parameters into a `Keys`, with validation
+* Update the `VAPIDKeys` struct to contain a `(*ecdsa.PrivateKey)`
+    * `VAPIDKeys` can no longer be compared with `==`; use `(*VAPIDKeys).Equal` instead
+    * The JSON representation is now a JSON string containing the PEM of the PKCS8-encoded private key
+    * To parse the legacy representation (raw bytes of the private key encoded in base64), use `DecodeLegacyVAPIDPrivateKey`
+* Renamed `SendNotificationWithContext` to `SendNotification`, removing the earlier `SendNotification` API. (Pass `context.Background()` as the context to restore the former behavior.)

README.md

@@ -1,12 +1,13 @@
 # webpush-go
 
-[![Go Report Card](https://goreportcard.com/badge/github.com/SherClockHolmes/webpush-go)](https://goreportcard.com/report/github.com/SherClockHolmes/webpush-go)
-[![GoDoc](https://godoc.org/github.com/SherClockHolmes/webpush-go?status.svg)](https://godoc.org/github.com/SherClockHolmes/webpush-go)
+[![GoDoc](https://godoc.org/github.com/ergochat/webpush-go?status.svg)](https://godoc.org/github.com/ergochat/webpush-go)
 
 Web Push API Encryption with VAPID support.
 
+This library is a fork of [SherClockHolmes/webpush-go](https://github.com/SherClockHolmes/webpush-go).
+
 ```bash
-go get -u github.com/SherClockHolmes/webpush-go
+go get -u github.com/ergochat/webpush-go/v2
 ```
 
 ## Example
@@ -19,20 +20,21 @@ package main
 import (
 	"encoding/json"
 
-	webpush "github.com/SherClockHolmes/webpush-go"
+	webpush "github.com/ergochat/webpush-go/v2"
 )
 
 func main() {
 	// Decode subscription
 	s := &webpush.Subscription{}
 	json.Unmarshal([]byte("<YOUR_SUBSCRIPTION>"), s)
+	vapidKeys := new(webpush.VAPIDKeys)
+	json.Unmarshal([]byte("<YOUR_VAPID_KEYS">), vapidKeys)
 
 	// Send Notification
 	resp, err := webpush.SendNotification([]byte("Test"), s, &webpush.Options{
 		Subscriber:      "example@example.com",
-		VAPIDPublicKey:  "<YOUR_VAPID_PUBLIC_KEY>",
-		VAPIDPrivateKey: "<YOUR_VAPID_PRIVATE_KEY>",
-		TTL:             30,
+		VAPIDKeys:       vapidKeys,
+		TTL:             3600, // seconds
 	})
 	if err != nil {
 		// TODO: Handle error
@@ -46,7 +48,7 @@ func main() {
 Use the helper method `GenerateVAPIDKeys` to generate the VAPID key pair.
 
 ```golang
-privateKey, publicKey, err := webpush.GenerateVAPIDKeys()
+vapidKeys, err := webpush.GenerateVAPIDKeys()
 if err != nil {
 	// TODO: Handle error
 }

example/main.go

@@ -1,29 +1,39 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
+	"time"
 
-	webpush "github.com/SherClockHolmes/webpush-go"
+	webpush "github.com/ergochat/webpush-go/v2"
 )
 
 const (
 	subscription    = ``
-	vapidPublicKey  = ""
 	vapidPrivateKey = ""
 )
 
 func main() {
 	// Decode subscription
-	s := &webpush.Subscription{}
-	json.Unmarshal([]byte(subscription), s)
+	sub := &webpush.Subscription{}
+	json.Unmarshal([]byte(subscription), sub)
+	// Decode VAPID keys
+	v := &webpush.VAPIDKeys{}
+	json.Unmarshal([]byte(vapidPrivateKey), v)
 
 	// Send Notification
-	resp, err := webpush.SendNotification([]byte("Test"), s, &webpush.Options{
-		Subscriber:      "example@example.com", // Do not include "mailto:"
-		VAPIDPublicKey:  vapidPublicKey,
-		VAPIDPrivateKey: vapidPrivateKey,
-		TTL:             30,
-	})
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	resp, err := webpush.SendNotification(
+		ctx,
+		[]byte("Test"),
+		sub,
+		&webpush.Options{
+			Subscriber: "example@example.com", // Do not include "mailto:"
+			VAPIDKeys:  v,
+			TTL:        30,
+		},
+	)
 	if err != nil {
 		// TODO: Handle error
 	}