Lens SDK

The @lens-protocol/graphql package provides gql.tada bindings for the Lens API.

Warning: This package is not intended for direct use by end-users. Its interface is unstable and may change without notice. Developers should use higher-level SDK packages (like @lens-protocol/client) instead of interacting with this package directly.

The @lens-protocol/env package manages Lens environments.

Warning: This package is not intended for direct use by end-users. Its interface is unstable and subject to change without notice. Using it directly in your application is done at your own risk.

When performing operations on a post, the SDK provides validation results via OperationValidationOutcomeFragment. This fragment returns a union of three possible states:

• PostOperationValidationPassed: The operation is valid.
• PostOperationValidationUnknown: The operation requires extra checks (returns extraChecksRequired).
• PostOperationValidationFailed: The operation is invalid (returns unsatisfiedRules and a reason).

The AccountFollowOperationValidationOutcome is a union type used to determine if a follow or unfollow operation is permitted. It can result in one of three states:

1. AccountFollowOperationValidationPassed: The operation is valid.
2. AccountFollowOperationValidationUnknown: Extra checks are required (returns AccountFollowOperationValidationUnknown).
3. AccountFollowOperationValidationFailed: The operation is invalid (returns AccountFollowOperationValidationFailed containing unsatisfiedRules).

In the Lens SDK, data stored in external storage is wrapped in an IStorageItem<Data> structure. This ensures that every piece of data is accompanied by versioning and timestamp metadata, which is critical for data migration and integrity.

A storage item consists of:

• data: The actual payload of type Data.
• metadata: A StorageMetadata object containing:
  • version: A positive integer representing the schema version.
  • createdAt: A positive integer timestamp.
  • updatedAt: A positive integer timestamp.

interface IStorageItem<Data> {
  data: Data;
  metadata: {
    version: number;
    createdAt: number;
    updatedAt: number;
  };
}

The @lens-protocol/react package supports React Suspense. When a hook is configured to use Suspense, it may return a SuspenseResult<T>, which simply contains the data property.

In a SuspendableResult<T> (which is ReadResult<T> | SuspenseResult<T>), the presence of data without a loading flag typically indicates that the component has successfully suspended and resumed with the required data.

export type SuspenseResult<T> = { data: T };
export type SuspendableResult<T> = ReadResult<T> | SuspenseResult<T>;

Lens uses a standardized validation pattern for operations (like posting to a feed, creating a namespace, or joining a group). The OperationValidationOutcome is a union type representing three possible states:

1. Passed: The operation is allowed.
2. Unknown: The operation requires extra checks (returns extraChecksRequired rules).
3. Failed: The operation is denied (returns unsatisfiedRules and a reason).

Specific fragments for these outcomes include:

• FeedOperationValidationOutcomeFragment (for Feeds)
• NamespaceOperationValidationOutcomeFragment (for Namespaces)
• GroupOperationValidationOutcomeFragment (for Groups)

When using read hooks in @lens-protocol/react, the returned data follows the ReadResult<T, E> discriminated union pattern. You should use the loading boolean to determine the state of the operation:

1. If loading is true, both data and error are undefined.
2. If loading is false and error is undefined, the data property contains the successful result of type T.
3. If loading is false and error is defined, the error property contains the error of type E.

This pattern ensures type safety when checking for data availability.

type ReadResult<T, E = never> =
  | { data: undefined; error: undefined; loading: true; }
  | { data: T; error: undefined; loading: false; }
  | { data: undefined; error: E; loading: false; };