feat: adding docs for payment metadata (#124)

Co-authored-by: vacwmX <vacwm01@gmail.com>
Co-authored-by: ok300 <106775972+ok300@users.noreply.github.com>

snippets/csharp/Metadata.cs

@@ -0,0 +1,78 @@
+using Breez.Sdk;
+using System.Text.Json;
+
+public class MetadataSnippets
+{
+    public void SetPaymentMetadata(BlockingBreezServices sdk)
+    {
+        // ANCHOR: set-payment-metadata
+        sdk.SetPaymentMetadata("target-payment-hash", "{\"myCustomValue\":true}");
+        // ANCHOR_END: set-payment-metadata
+    }
+
+    public void FilterPaymentMetadata(BlockingBreezServices sdk)
+    {
+        // ANCHOR: filter-payment-metadata
+        try
+        {
+            var metadataFilters = new List<MetadataFilter>() {
+              new MetadataFilter(
+                jsonPath: "myCustomValue",
+                jsonValue: "true"
+              )
+            };
+
+            var payments = sdk.ListPayments(
+                new ListPaymentsRequest(
+                    metadataFilters: metadataFilters
+                )
+            );
+        }
+        catch (Exception)
+        {
+            // Handle error
+        }
+        // ANCHOR_END: filter-payment-metadata
+    }
+
+    public void FilterPaymentMetadataString(BlockingBreezServices sdk)
+    {
+        // ANCHOR: filter-payment-metadata-string
+        var metadataFilters = new List<MetadataFilter>() {
+          new MetadataFilter(
+            jsonPath: "customerName",
+            jsonValue: "\"Satoshi Nakamoto\""
+          ),
+          new MetadataFilter(
+            jsonPath: "customerName",
+            jsonValue: JsonSerializer.Serialize("Satoshi Nakamoto")
+          )
+        };
+        // ANCHOR_END: filter-payment-metadata-string
+    }
+
+    public void FilterPaymentMetadataObject(BlockingBreezServices sdk)
+    {
+        // ANCHOR: filter-payment-metadata-object
+        // This will *NOT* work
+        var _metadataFilters = new List<MetadataFilter>() {
+          new MetadataFilter(
+            jsonPath: "parent.nestedArray",
+            jsonValue: "[1, 2, 3]"
+          )
+        };
+
+        // Any of these will work
+        var metadataFilters = new List<MetadataFilter>() {
+          new MetadataFilter(
+            jsonPath: "parent.nestedArray",
+            jsonValue: "[1,2,3]"
+          ),
+          new MetadataFilter(
+            jsonPath: "parent.nestedArray",
+            jsonValue: JsonSerializer.Serialize(new int[] {1, 2, 3})
+          )
+        };
+        // ANCHOR_END: filter-payment-metadata-object
+    }
+}

snippets/dart_snippets/lib/metadata.dart

@@ -0,0 +1,51 @@
+import 'package:breez_sdk/breez_sdk.dart';
+import 'package:breez_sdk/bridge_generated.dart';
+
+Future<void> setPaymentMetadata({required String paymentHash, required String metadata}) async {
+  // ANCHOR: set-payment-metadata
+  await BreezSDK().setPaymentMetadata(hash: "target-payment-hash", metadata: '{"myCustomValue":true}');
+  // ANCHOR_END: set-payment-metadata
+}
+
+Future<void> filterPaymentMetadata() async {
+  // ANCHOR: filter-payment-metadata
+  List<MetadataFilter> metadataFilters = [
+    MetadataFilter(
+      jsonPath: "myCustomValue",
+      jsonValue: "true",
+    ),
+  ];
+
+  await BreezSDK().listPayments(
+    req: ListPaymentsRequest(
+      metadataFilters: metadataFilters
+    ));
+  // ANCHOR_END: filter-payment-metadata
+
+  // ANCHOR: filter-payment-metadata-string
+  metadataFilters = [
+    MetadataFilter(
+      jsonPath: "customerName",
+      jsonValue: '"Satoshi Nakamoto"',
+    ),
+  ];
+  // ANCHOR_END: filter-payment-metadata-string
+
+  // ANCHOR: filter-payment-metadata-object
+  // This will *NOT* work
+  metadataFilters = [
+    MetadataFilter(
+      jsonPath: "parent.nestedArray",
+      jsonValue: "[1, 2, 3]",
+    ),
+  ];
+
+  // Any of these will work
+  metadataFilters = [
+    MetadataFilter(
+      jsonPath: "parent.nestedArray",
+      jsonValue: "[1,2,3]",
+    ),
+  ];
+  // ANCHOR_END: filter-payment-metadata-object
+}

snippets/go/metadata.go

@@ -0,0 +1,72 @@
+package example
+
+import (
+	"encoding/json"
+	"log"
+
+	"github.com/breez/breez-sdk-go/breez_sdk"
+)
+
+func SetPaymentMetadata() {
+	// ANCHOR: set-payment-metadata
+	sdk.SetPaymentMetadata("target-payment-hash", `{"myCustomValue":true}`)
+	// ANCHOR_END: set-payment-metadata
+}
+
+func FilterPaymentMetadata() {
+	// ANCHOR: filter-payment-metadata
+	metadataFilters := []breez_sdk.MetadataFilter{
+		{JsonPath: "myCustomValue", JsonValue: "true"},
+	}
+
+	payments, err := sdk.ListPayments(breez_sdk.ListPaymentsRequest{
+		MetadataFilters: &metadataFilters,
+	})
+
+	if err != nil {
+		// handle error
+	}
+	// ANCHOR_END: filter-payment-metadata
+	log.Printf("%#v", payments)
+}
+
+func FilterPaymentMetadataString() {
+	// ANCHOR: filter-payment-metadata-string
+	metadataFilters := []breez_sdk.MetadataFilter{
+		{JsonPath: "customerName", JsonValue: "\"Satoshi Nakamoto\""},
+	}
+
+	jsonValue, _ := json.Marshal("Satoshi Nakamoto")
+	metadataFilters = []breez_sdk.MetadataFilter{
+		{
+			JsonPath:  "customerName",
+			JsonValue: string(jsonValue),
+		},
+	}
+	// ANCHOR_END: filter-payment-metadata-string
+
+	sdk.ListPayments(breez_sdk.ListPaymentsRequest{
+		MetadataFilters: &metadataFilters,
+	})
+}
+
+func FilterPaymentMetadataObject() {
+	// ANCHOR: filter-payment-metadata-object
+	// This will *NOT* work
+	metadataFilters := []breez_sdk.MetadataFilter{
+		{JsonPath: "parent.nestedArray", JsonValue: "[1, 2, 3]"},
+	}
+
+	// Any of these will work
+	jsonValue, _ := json.Marshal([]int{1, 2, 3})
+
+	metadataFilters = []breez_sdk.MetadataFilter{
+		{JsonPath: "parent.nestedArray", JsonValue: "[1,2,3]"},
+		{JsonPath: "parent.nestedArray", JsonValue: string(jsonValue)},
+	}
+	// ANCHOR_END: filter-payment-metadata-object
+
+	sdk.ListPayments(breez_sdk.ListPaymentsRequest{
+		MetadataFilters: &metadataFilters,
+	})
+}

snippets/kotlin_mpp_lib/shared/src/commonMain/kotlin/com/example/kotlinmpplib/Metadata.kt

@@ -0,0 +1,57 @@
+package com.example.kotlinmpplib
+
+import breez_sdk.*
+class Metadata {
+    fun SetPaymentMetadata(sdk: BlockingBreezServices) {
+        // ANCHOR: set-payment-metadata
+        try {
+            sdk.setPaymentMetadata("target-payment-hash", """{"myCustomValue":true}""")
+        } catch (e: Exception) {
+            // Handle error
+        }
+        // ANCHOR_END: set-payment-metadata
+    }
+
+    fun FilterPaymentMetadata(sdk: BlockingBreezServices) {
+        // ANCHOR: filter-payment-metadata
+        val metadataFilters = listOf(MetadataFilter(
+          jsonPath = "myCustomValue",
+          jsonValue = "true"
+        ))
+
+        try {
+            sdk.listPayments(
+                ListPaymentsRequest(
+                    metadataFilters = metadataFilters
+                ))
+        } catch (e: Exception) {
+            // handle error
+        }
+        // ANCHOR_END: filter-payment-metadata
+    }
+
+    fun FilterPaymentMetadataString(sdk: BlockingBreezServices) {
+        // ANCHOR: filter-payment-metadata-string
+        val metadataFilters = listOf(MetadataFilter(
+          jsonPath = "customerName",
+          jsonValue = "\"Satoshi Nakamoto\""
+        ))
+        // ANCHOR_END: filter-payment-metadata-string
+    }
+
+    fun FilterPaymentMetadataObject(sdk: BlockingBreezServices) {
+        // ANCHOR: filter-payment-metadata-object
+        // This will *NOT* work
+        val _metadataFilters = listOf(MetadataFilter(
+          jsonPath = "parent.nestedArray",
+          jsonValue = "[1, 2, 3]"
+        ))
+
+        // Any of these will work
+        val metadataFilters = listOf(MetadataFilter(
+          jsonPath = "parent.nestedArray",
+          jsonValue = "[1,2,3]"
+        ))
+        // ANCHOR_END: filter-payment-metadata-object
+    }
+}

snippets/python/src/metadata.py

@@ -0,0 +1,45 @@
+import breez_sdk
+
+def set_payment_metadata(sdk_services):
+    try: 
+        # ANCHOR: set-payment-metadata
+        sdk_services.set_payment_metadata("target-payment-hash", '{"myCustomValue":true}')    
+        # ANCHOR_END: set-payment-metadata
+    except Exception as error: 
+        # handle error
+        raise
+
+def filter_payment_metadata(sdk_services):
+    # ANCHOR: filter-payment-metadata
+    metadata_filters = [
+        breez_sdk.MetadataFilter("myCustomValue", "true")
+    ]
+
+    try:
+        sdk_services.list_payments(breez_sdk.ListPaymentsRequest(
+            metadata_filters = metadata_filters
+        ))
+    except Exception as error:
+        # handle error
+        raise
+    # ANCHOR_END: filter-payment-metadata
+
+    # ANCHOR: filter-payment-metadata-string
+    metadata_filters = [
+        breez_sdk.MetadataFilter("customerName", "\"Satoshi Nakamoto\""),
+        breez_sdk.MetadataFilter("customerName", json.dumps("Satoshi Nakamoto")),
+    ]
+    # ANCHOR_END: filter-payment-metadata-string
+
+    # ANCHOR: filter-payment-metadata-object
+    # This will *NOT* work
+    metadata_filters = [
+        breez_sdk.MetadataFilter("parent.nestedArray", "[1, 2, 3]")
+    ]
+
+    # Any of these will work
+    metadata_filters = [
+        breez_sdk.MetadataFilter("parent.nestedArray", "[1,2,3]"),
+        breez_sdk.MetadataFilter("parent.nestedArray", json.dumps([1,2,3], separators=(',', ':'))),
+    ]
+    # ANCHOR_END: filter-payment-metadata-object

snippets/react-native/metadata.ts

@@ -0,0 +1,66 @@
+import { setPaymentMetadata, listPayments } from '@breeztech/react-native-breez-sdk'
+
+const testSetPaymentMetadata = async () => {
+  // ANCHOR: set-payment-metadata
+  await setPaymentMetadata('target-payment-hash', '{"myCustomValue":true}')
+  // ANCHOR_END: set-payment-metadata
+}
+
+const testFilterPaymentMetadata = async () => {
+  // ANCHOR: filter-payment-metadata
+  const metadataFilters = [
+    {
+      jsonPath: 'myCustomValue',
+      jsonValue: 'true'
+    }
+  ]
+
+  try {
+    await listPayments({
+      metadataFilters
+    })
+  } catch (err) {
+    // handle error
+  }
+  // ANCHOR_END: filter-payment-metadata
+}
+
+const testFilterPaymentMetadataString = async () => {
+  // ANCHOR: filter-payment-metadata-string
+  // Note: These are equivalent
+  const metadataFilters = [
+    {
+      jsonPath: 'customerName',
+      jsonValue: 'Satoshi Nakamoto'
+    },
+    {
+      jsonPath: 'customerName',
+      jsonValue: JSON.stringify('Satoshi Nakamoto')
+    }
+  ]
+  // ANCHOR_END: filter-payment-metadata-string
+}
+
+const testFilterPaymentMetadataObject = async () => {
+  // ANCHOR: filter-payment-metadata-object
+  // This will *NOT* work
+  const _metadataFilters = [
+    {
+      jsonPath: 'parent.nestedArray',
+      jsonValue: '[1, 2, 3]'
+    }
+  ]
+
+  // Any of these will work
+  const metadataFilters = [
+    {
+      jsonPath: 'parent.nestedArray',
+      jsonValue: '[1,2,3]'
+    },
+    {
+      jsonPath: 'parent.nestedArray',
+      jsonValue: JSON.stringify([1, 2, 3])
+    }
+  ]
+  // ANCHOR_END: filter-payment-metadata-object
+}

snippets/rust/src/metadata.rs

@@ -0,0 +1,73 @@
+use std::sync::Arc;
+use anyhow::Result;
+use breez_sdk_core::*;
+
+async fn set_payment_metadata(sdk: Arc<BreezServices>) -> Result<()> {
+  // ANCHOR: set-payment-metadata
+    sdk.set_payment_metadata("target-payment-hash", r#"{"myCustomValue":true}"#).await?;
+  // ANCHOR_END: set-payment-metadata
+  
+    Ok(())
+}
+
+async fn filter_payment_metadata(sdk: Arc<BreezServices>) -> Result<()> {
+  // ANCHOR: filter-payment-metadata
+    let metadata_filters = vec![
+        MetadataFilter {
+            json_path: "myCustomValue".to_string(),
+            json_value: "true".to_string(),
+        },
+    ];
+
+    sdk.list_payments(ListPaymentsRequest {
+        metadata_filters,
+        ..Default::default(),
+    }).await?;
+  // ANCHOR_END: filter-payment-metadata
+}
+
+async fn filter_payment_metadata_string(sdk: Arc<BreezServices>) -> Result<()> {
+  // ANCHOR: filter-payment-metadata-string
+    // Note: The following are equivalent
+    let metadata_filters = vec![
+        MetadataFilter {
+            json_path: "customerName".to_string(),
+            json_value: r#""Satoshi Nakamoto""#.to_string(),
+        },
+        MetadataFilter {
+            json_path: "customerName".to_string(),
+            json_value: serde_json::json!("Satoshi Nakamoto").to_string(),
+        },
+    ];
+  // ANCHOR_END: filter-payment-metadata-string
+}
+
+async fn filter_payment_metadata_object(sdk: Arc<BreezServices>) -> Result<()> {
+  // ANCHOR: filter-payment-metadata-object
+    // This will *NOT* work
+    let metadata_filters = vec![
+        MetadataFilter {
+            json_path: "parent.nestedArray".to_string(),
+            json_value: r#"[1, 2, 3]"#.to_string(),
+        },
+    ];
+
+    // Any of these will work
+    let metadata_filters = vec![
+        MetadataFilter {
+            json_path: "parent.nestedArray".to_string(),
+            json_value: r#"[1,2,3]"#.to_string(),
+        },
+    ];
+  // ANCHOR_END: filter-payment-metadata-object
+  
+  // ANCHOR: filter-payment-metadata-object-serde
+    let metadata_filters = vec![
+        MetadataFilter {
+            json_path: "parent.nestedArray".to_string(),
+            json_value: serde_json::json!(&[1, 2, 3]).to_string(),
+        },
+    ];
+  // ANCHOR_END: filter-payment-metadata-object-serde
+    Ok(())
+}

snippets/swift/BreezSDKExamples/Sources/Metadata.swift

@@ -0,0 +1,76 @@
+//
+//  Metadata.swift
+//  
+//
+//
+
+import Foundation
+import BreezSDK
+
+func SetPaymentMetadata(sdk: BlockingBreezServices) throws {
+    // ANCHOR: set-payment-metadata
+    try sdk.setPaymentMetadata(hash: "target-payment-hash", metadata: #"{"myCustomValue":true}"#)    
+    // ANCHOR_END: set-payment-metadata
+}
+
+func FilterPaymentMetadata(sdk: BlockingBreezServices) -> [Payment]? {
+    // ANCHOR: filter-payment-metadata
+    let metadataFilters = [
+        MetadataFilter(
+            jsonPath: "myCustomValue",
+            jsonValue: "true"
+        )
+    ]
+
+    let payments = try? sdk.listPayments(
+        req: ListPaymentsRequest(
+            metadataFilters: metadataFilters
+        )
+    )
+    // ANCHOR_END: filter-payment-metadata
+
+    return payments
+}
+
+func FilterPaymentMetadataString(sdk: BlockingBreezServices) -> [Payment]? {
+    // ANCHOR: filter-payment-metadata-string
+    let metadataFilters = [
+        MetadataFilter(
+            jsonPath: "myCustomValue",
+            jsonValue: #""true""#
+        )
+    ]
+    // ANCHOR_END: filter-payment-metadata-string
+
+    return try? sdk.listPayments(
+        req: ListPaymentsRequest(
+            metadataFilters: metadataFilters
+        )
+    )
+}
+
+func FilterPaymentMetadataObject(sdk: BlockingBreezServices) -> [Payment]? {
+    // ANCHOR: filter-payment-metadata-object
+    // This will *NOT* work
+    var metadataFilters = [
+        MetadataFilter(
+            jsonPath: "myCustomValue",
+            jsonValue: #"[1, 2, 3]"#
+        )
+    ]
+
+    // Any of these will work
+    metadataFilters = [
+        MetadataFilter(
+            jsonPath: "myCustomValue",
+            jsonValue: #"[1,2,3]"#
+        )
+    ]
+    // ANCHOR_END: filter-payment-metadata-object
+
+    return try? sdk.listPayments(
+        req: ListPaymentsRequest(
+            metadataFilters: metadataFilters
+        )
+    )
+}