docs: explain configurable metadata and native attachments

apps/docs/examples/attachments-browser.ts

@@ -0,0 +1,44 @@
+import {
+  type Client,
+  type Group,
+  type RemoteAttachment,
+} from "@xmtp/browser-sdk";
+import { initPureWasm, RemoteAttachmentCodec } from "@xmtp/browser-sdk/pure";
+
+export async function sendAttachment(
+  client: Client,
+  group: Group,
+  path: string,
+) {
+  // #region upload
+  await initPureWasm();
+  const attachments = client.attachments;
+  if (!attachments.offered) {
+    throw new Error("The backend does not offer attachments");
+  }
+
+  const pending = await attachments.create({
+    kind: "path",
+    path,
+    filename: "photo.jpg",
+    mimeType: "image/jpeg",
+  });
+  const remote = pending.remoteAttachment;
+  await group.send(new RemoteAttachmentCodec(), remote);
+  await pending.upload();
+  // #endregion upload
+  return remote;
+}
+
+export async function downloadAttachment(
+  client: Client,
+  remote: RemoteAttachment,
+) {
+  // #region download
+  const downloaded = await client.attachments.download(remote);
+  const path = downloaded.path;
+  const mimeType = downloaded.mimeType;
+  const filename = downloaded.filename;
+  // #endregion download
+  return { path, mimeType, filename };
+}

apps/docs/examples/attachments-node.ts

@@ -0,0 +1,43 @@
+import {
+  type Client,
+  type Group,
+  type RemoteAttachment,
+  RemoteAttachmentCodec,
+} from "@xmtp/node-sdk";
+
+export async function sendAttachment(
+  client: Client,
+  group: Group,
+  path: string,
+) {
+  // #region upload
+  const attachments = client.attachments;
+  if (!attachments.offered) {
+    throw new Error("The backend does not offer attachments");
+  }
+
+  const pending = await attachments.create({
+    kind: "path",
+    path,
+    filename: "photo.jpg",
+    mimeType: "image/jpeg",
+  });
+  const remote = pending.remoteAttachment;
+  await group.send(new RemoteAttachmentCodec(), remote);
+  await pending.upload();
+  // #endregion upload
+  return remote;
+}
+
+export async function downloadAttachment(
+  client: Client,
+  remote: RemoteAttachment,
+) {
+  // #region download
+  const downloaded = await client.attachments.download(remote);
+  const path = downloaded.path;
+  const mimeType = downloaded.mimeType;
+  const filename = downloaded.filename;
+  // #endregion download
+  return { path, mimeType, filename };
+}

apps/docs/examples/metadata-fields-browser.ts

@@ -0,0 +1,29 @@
+import type { Group } from "@xmtp/browser-sdk";
+
+export async function updateFields(group: Group) {
+  // #region update
+  const category = await group.metadataField("GROUP_CATEGORY");
+  const displayName = await group.metadataField("USER_DISPLAY_NAME");
+  const pronouns = await group.metadataField("USER_PRONOUNS");
+  if (!category || !displayName || !pronouns) {
+    throw new Error("The group has not registered the required fields");
+  }
+
+  await group.updateMetadataField(category.field, {
+    kind: "replace",
+    value: { kind: "string", value: "engineering" },
+  });
+  await group.updateUserData([
+    { field: displayName.field, value: { kind: "string", value: "Alix" } },
+    { field: pronouns.field, value: { kind: "string", value: "they/them" } },
+  ]);
+
+  await group.sync();
+  const profiles = await group.userData(
+    [displayName.field, pronouns.field],
+    undefined,
+  );
+  await group.updateUserData([{ field: pronouns.field, value: undefined }]);
+  // #endregion update
+  return profiles;
+}

apps/docs/examples/metadata-fields-node.ts

@@ -0,0 +1,29 @@
+import type { Group } from "@xmtp/node-sdk";
+
+export async function updateFields(group: Group) {
+  // #region update
+  const category = await group.metadataField("GROUP_CATEGORY");
+  const displayName = await group.metadataField("USER_DISPLAY_NAME");
+  const pronouns = await group.metadataField("USER_PRONOUNS");
+  if (!category || !displayName || !pronouns) {
+    throw new Error("The group has not registered the required fields");
+  }
+
+  await group.updateMetadataField(category.field, {
+    kind: "replace",
+    value: { kind: "string", value: "engineering" },
+  });
+  await group.updateUserData([
+    { field: displayName.field, value: { kind: "string", value: "Alix" } },
+    { field: pronouns.field, value: { kind: "string", value: "they/them" } },
+  ]);
+
+  await group.sync();
+  const profiles = await group.userData(
+    [displayName.field, pronouns.field],
+    undefined,
+  );
+  await group.updateUserData([{ field: pronouns.field, value: undefined }]);
+  // #endregion update
+  return profiles;
+}

apps/docs/scripts/search-config.mjs

@@ -9,5 +9,5 @@ export const searchRanking = {
   termSaturation: 2,
   termSimilarity: 9,
   // Keep guide title matches above repeated terms in longer guide bodies.
-  metaWeights: { title: 0, guideTitle: 100 },
+  metaWeights: { title: 0, guideTitle: 1000 },
 };