fix: TSDoc, new TypeDoc theme, re-export of common React APIs (#846)

* fix: TSDoc, new TypeDoc theme, re-export of common React APIs

* Fixes linting issue

* Removes invalid TSDoc tag

.changeset/neat-moons-study.md

@@ -0,0 +1,8 @@
+---
+"@lens-protocol/react-native": patch
+"@lens-protocol/react-web": patch
+"@lens-protocol/client": patch
+"@lens-protocol/react": patch
+---
+
+**fix:** TSDoc and better exporting of shared parts

assets/docs.css

@@ -0,0 +1,9 @@
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=SF+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap");
+
+:root,
+:root[data-theme="light"],
+:root[data-theme="dark"] {
+  --font-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica,
+    "Apple Color Emoji", Arial, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol" !important;
+  --font-mono: "SF Mono", "SFMono-Regular", "Consolas", "Liberation Mono", Menlo, Courier, monospace !important;
+}

package.json

@@ -21,12 +21,13 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.2",
-    "@mxssfd/typedoc-theme": "^1.1.3",
     "@preconstruct/cli": "^2.8.1",
     "prettier": "^2.8.8",
     "rimraf": "^4.4.1",
     "turbo": "^1.10.16",
-    "typedoc": "^0.25.3",
+    "typedoc": "^0.25.8",
+    "typedoc-material-theme": "^1.0.2",
+    "typedoc-plugin-extras": "^3.0.0",
     "typescript": "5.2.2"
   },
   "resolutions": {

packages/client/README.md

@@ -1,5 +1,53 @@
-# `@lens-protocol/client`
+# Lens JavaScript SDK
 
-The official framework-agnostic Lens API Client.
+The official framework-agnostic JavaScript SDK for Lens Protocol.
+
+---
 
 This package enables you to interact with the Lens API via a type safe interface that abstracts away some of the GraphQL intricacies.
+
+## Documentation
+
+- [GitHub monorepo](https://github.com/lens-protocol/lens-sdk)
+- [Getting Started](https://docs.lens.xyz/docs/lensclient-sdk-1)
+- [Reference](https://lens-protocol.github.io/lens-sdk/modules/_lens_protocol_client.html)
+
+## Quick start
+
+Install the Lens React Native SDK package using your package manager of choice:
+
+| Package Manager | Command                                    |
+| :-------------: | :----------------------------------------- |
+|       npm       | `npm install @lens-protocol/client@latest` |
+|      yarn       | `yarn add @lens-protocol/client@latest`    |
+|      pnpm       | `pnpm add @lens-protocol/client@latest`    |
+
+Development configuration example:
+
+```ts
+import { LensClient, development } from '@lens-protocol/client';
+
+const client = new LensClient({
+  environment: development,
+});
+```
+
+Production configuration example:
+
+```ts
+import { LensClient, production } from '@lens-protocol/client';
+
+const client = new LensClient({
+  environment: production,
+});
+```
+
+In a browser-based implementation you can use the [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) to persist authentication state.
+
+```ts
+const client = new LensClient({
+  environment: production,
+
+  storage: window.localStorage,
+});
+```

packages/client/package.json

@@ -115,5 +115,10 @@
   },
   "peerDependencies": {
     "@lens-protocol/metadata": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@lens-protocol/metadata": {
+      "optional": true
+    }
   }
 }

packages/client/src/LensClient.ts

@@ -24,6 +24,8 @@ import {
 
 /**
  * LensClient configuration
+ *
+ * @group LensClient
  */
 export type LensClientConfig = {
   /**

packages/client/src/gated/LensClient.ts

@@ -10,6 +10,11 @@ import { InMemoryStorageProvider } from '@lens-protocol/storage';
 import * as core from '../LensClient';
 import { Gated } from './Gated';
 
+/**
+ * The configuration for the LensClient
+ *
+ * @group LensClient
+ */
 export type LensClientConfig = core.LensClientConfig & {
   /**
    * The authentication configuration to use for authenticating with the Lit Protocol network.
@@ -73,6 +78,8 @@ export type LensClientConfig = core.LensClientConfig & {
  *   signer: await provider.getSigner(),
  * });
  * ```
+ *
+ * @group LensClient
  */
 export class LensClient extends core.LensClient {
   private _gated: Gated;

packages/client/src/gated/index.ts

@@ -12,18 +12,18 @@
  *
  * ## Quick start
  *
- * Install:
+ * Install the required peer dependencies.
  *
  * ```bash
- * npm install zod @lens-protocol/metadata@latest @lens-protocol/client@alpha
+ * npm install zod @lens-protocol/metadata@latest
  *
  * # OR
  *
- * yarn add zod @lens-protocol/metadata@latest @lens-protocol/client@alpha
+ * yarn add zod @lens-protocol/metadata@latest
  *
  * # OR
  *
- * pnpm add zod @lens-protocol/metadata@latest @lens-protocol/client@alpha
+ * pnpm add zod @lens-protocol/metadata@latest
  * ```
  *
  * Typical NodeJS setup:
@@ -190,19 +190,19 @@
  *
  * @module Gated
  */
-import { LensClientConfig, LensClient } from './LensClient';
+import { LensClient, LensClientConfig } from './LensClient';
 
 export * from '../index';
 export * from './Gated';
 
 // NOTE: local exports takes priority over package exports, basically overriding the LensClient and
 // see https://github.com/systemjs/systemjs/issues/1031#issuecomment-171262430
-export type { LensClientConfig };
 export { LensClient };
+export type { LensClientConfig };
 
 export { isEncryptedPublicationMetadata } from '@lens-protocol/gated-content';
 export type {
   AuthenticationConfig,
-  ISigner,
   IEncryptionProvider,
+  ISigner,
 } from '@lens-protocol/gated-content';

packages/client/src/index.ts

@@ -1,42 +1,16 @@
 /**
- * @module Core
- *
- * @example
- * Development example:
- * ```ts
- * import { LensClient, development } from '@lens-protocol/client';
- *
- * const client = new LensClient({
- *   environment: development
- * });
- * ```
- *
- * @example
- * Production example:
- * ```ts
- * import { LensClient, production } from '@lens-protocol/client';
+ * The primary entry point of the `@lens-protocol/client` package.
  *
- * const client = new LensClient({
- *   environment: production
- * });
- * ```
+ * See {@link Gated} for token-gated support.
  *
- * @example
- * Use [Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) to persist authentication state:
- * ```ts
- * const client = new LensClient({
- *   environment: production,
- *
- *   storage: window.localStorage,
- * });
- * ```
+ * @module Core
  */
 
 export * from './LensClient';
+export * from './authentication';
 export * from './environments';
 export * from './errors';
 export * from './graphql';
-export * from './authentication';
 export * from './submodules';
 
 // types
@@ -54,6 +28,6 @@ export type {
   Success,
 } from '@lens-protocol/shared-kernel';
 export type { IStorageProvider, InMemoryStorageProvider } from '@lens-protocol/storage';
+export type { PaginatedQueryData, PaginatedResult } from './helpers/buildPaginatedQueryResult';
+export type { AppId, MediaTransformsConfig, QueryParams } from './queryParams';
 export type { TypedData, TypedDataResponse } from './types';
-export type { MediaTransformsConfig, AppId, QueryParams } from './queryParams';
-export type { PaginatedResult, PaginatedQueryData } from './helpers/buildPaginatedQueryResult';

packages/client/typedoc.json

@@ -3,5 +3,6 @@
   "extends": ["../../typedoc.base.json"],
   "entryPoints": ["src/index.ts", "src/gated/index.ts"],
   "intentionallyNotExported": ["Environment", "Typename", "PickByTypename"],
-  "groupOrder": ["LensClient", "LensClient Modules", "Variables", "Functions"]
+  "groupOrder": ["LensClient", "LensClient Modules", "Variables", "Functions"],
+  "readme": "./README.md"
 }

packages/react-native/README.md

@@ -1,11 +1,78 @@
-# `@lens-protocol/react-native`
+# Lens React Native SDK
 
 The official Lens Protocol React bindings for React Native.
 
+---
+
 This package enables you to build mobile applications on top of the Lens Protocol using React Native.
 
 ## Documentation
 
 - [GitHub monorepo](https://github.com/lens-protocol/lens-sdk)
-- [Getting Started](https://lens-protocol.github.io/lens-sdk/modules/_lens_protocol_react_web.html#md:quick-start)
-- [SDK Reference](https://lens-protocol.github.io/lens-sdk/modules/_lens_protocol_react_web.html)
+- [Reference](https://lens-protocol.github.io/lens-sdk/modules/_lens_protocol_react_native.html)
+
+## Quick start
+
+Install the Lens React Native SDK package using your package manager of choice:
+
+| Package Manager | Command                                          |
+| :-------------: | :----------------------------------------------- |
+|       npm       | `npm install @lens-protocol/react-native@latest` |
+|      yarn       | `yarn add @lens-protocol/react-native@latest`    |
+|      pnpm       | `pnpm add @lens-protocol/react-native@latest`    |
+
+First we need to create so-called bindings. Bindings are just an object implementing the `IBindings` interface. This is used by the Lens SDK to access the Signer and the Provider.
+
+In this example we will limit ourselves to the bare minimum and we will use the `ethers.js` library to create the bindings.
+
+```ts
+// wallet.ts
+import { IBindings } from '@lens-protocol/react-native';
+import { providers, Wallet } from 'ethers';
+
+const provider = new providers.InfuraProvider('maticmum');
+const wallet = new Wallet('<your-private-key>', provider);
+
+export const bindings: IBindings = {
+  getProvider: async () => provider,
+  getSigner: async () => wallet,
+};
+```
+
+Create the `LensConfig`. In this example we will use `react-native-mmkk` as underlying storage. You can use any storage you want as long as it implements the `IStorageProvider` interface.
+
+First install the `react-native-mmkv` package:
+
+| Package Manager | Command                         |
+| :-------------: | :------------------------------ |
+|       npm       | `npm install react-native-mmkv` |
+|      yarn       | `yarn add react-native-mmkv`    |
+|      pnpm       | `pnpm add react-native-mmkv`    |
+
+Create the `LensConfig` object:
+
+```ts
+import { LensConfig, development } from '@lens-protocol/react-web';
+import { storage } from '@lens-protocol/react-web/storage/mmkv';
+import { bindings } from './wallet.ts';
+
+const lensConfig: LensConfig = {
+  bindings,
+  environment: development,
+  storage: storage(),
+};
+```
+
+Wrap your app with the `<LensProvider>` and pass the `LensConfig` as a prop.
+
+```tsx
+import { LensProvider } from '@lens-protocol/react-web';
+
+function App() {
+  return (
+    <LensProvider config={lensConfig}>
+      <YourApp />
+    </LensProvider>
+  );
+}
+```

packages/react-native/src/LensProvider.tsx

@@ -0,0 +1,74 @@
+import { BaseProvider, EnvironmentConfig, IBindings, QueryParams } from '@lens-protocol/react';
+import { ILogger } from '@lens-protocol/shared-kernel';
+import { IObservableStorageProvider, IStorageProvider } from '@lens-protocol/storage';
+import { ReactNode } from 'react';
+
+/**
+ * `<LensProvider>` configuration
+ */
+export type LensConfig = {
+  /**
+   * Provides integration with the ethers.js Signer and Provider
+   */
+  bindings: IBindings;
+  /**
+   * The environment to use. See {@link production} or {@link development}.
+   */
+  environment: EnvironmentConfig;
+  /**
+   * The logger interface to use when something worth logging happens
+   *
+   * @defaultValue `ConsoleLogger`, an internal implementation of `ILogger` interface that logs to the console
+   */
+  logger?: ILogger;
+  /**
+   * Enable debug mode. Disable gas estimation on self-funded transactions.
+   *
+   * @defaultValue `false`
+   */
+  debug?: boolean;
+  /**
+   * The storage provider to use.
+   *
+   * If a implementation of {@link IObservableStorageProvider} is provided,
+   * the provider will be used to subscribe to changes in the storage.
+   */
+  storage: IStorageProvider | IObservableStorageProvider;
+  /**
+   * The common query params allow you customize some aspect of the returned data.
+   */
+  params?: QueryParams;
+  /**
+   * The value of the `Origin` HTTP header to use when making requests to the Lens API.
+   *
+   * @example
+   * ```md
+   * https://example.xyz
+   * ```
+   *
+   * @defaultValue if not provided, the requests will be made without the `Origin` header.
+   */
+  origin?: string;
+};
+
+/**
+ * <LensProvider> props
+ */
+export type LensProviderProps = {
+  /**
+   * The children to render
+   */
+  children: ReactNode;
+  /**
+   * The configuration for the Lens SDK
+   */
+  config: LensConfig;
+};
+
+/**
+ * Manages the lifecycle and internal state of the Lens SDK
+ *
+ * @group Components
+ * @param props - {@link LensProviderProps}
+ */
+export const LensProvider = BaseProvider<LensConfig>;