@atproto/lex-schema 0.0.11 → 0.0.13

package/dist/schema/payload.d.ts

@@ -1,24 +1,120 @@
 import { LexValue } from '@atproto/lex-data';
-import { Infer, Schema } from '../core.js';
-import { ObjectSchema, ObjectSchemaShape } from './object.js';
-export type InferPayload<TPayload extends Payload, TBody> = TPayload['encoding'] extends infer E extends string ? {
-    encoding: SchemaEncodingToDataEncoding<E>;
-    body: InferPayloadBody<TPayload, TBody>;
-} : void | undefined;
-export type SchemaEncodingToDataEncoding<E extends string> = E extends '*/*' ? `${string}/${string}` : E extends `${infer T extends string}/*` ? `${T}/${string}` : E;
-export type InferPayloadEncoding<TPayload extends Payload> = TPayload['encoding'] extends string ? SchemaEncodingToDataEncoding<TPayload['encoding']> : undefined;
-export type InferPayloadBody<TPayload extends Payload, TBody> = TPayload['encoding'] extends undefined ? undefined : TPayload['schema'] extends Schema ? Infer<TPayload['schema']> : TPayload['encoding'] extends `application/json` ? LexValue : TBody;
-export type PayloadShape<E extends string | undefined> = E extends undefined ? undefined : Schema | undefined;
-export declare class Payload<const TEncoding extends string | undefined = string | undefined, const TPayload extends PayloadShape<TEncoding> = PayloadShape<TEncoding>> {
+import { Infer, Schema, Validator } from '../core.js';
+import { ObjectSchema } from './object.js';
+export type { LexValue };
+type ToBodyMime<TEncoding extends string> = TEncoding extends '*/*' ? `${string}/${string}` : TEncoding extends `${infer T extends string}/*` ? `${T}/${string}` : TEncoding;
+type ToBodyType<TEncoding extends string, TSchema, TBinary> = TSchema extends Schema ? Infer<TSchema> : TEncoding extends `application/json` ? LexValue : TBinary;
+/**
+ * Infers the type of a Payload's encoding and body.
+ *
+ * @template TPayload - The Payload type
+ * @template TBody - Fallback body type for non-JSON encodings
+ */
+export type InferPayload<TPayload extends Payload, TBinary> = TPayload extends Payload<infer TEncoding, infer TSchema> ? TEncoding extends string ? {
+    encoding: ToBodyMime<TEncoding>;
+    body: ToBodyType<TEncoding, TSchema, TBinary>;
+} : undefined : never;
+/**
+ * Converts schema encoding patterns to data encoding types.
+ *
+ * Handles wildcards like '*\/*' and 'image/*' in MIME types.
+ *
+ * @template TPayload - The Payload type
+ */
+export type InferPayloadEncoding<TPayload extends Payload> = TPayload extends Payload<infer TEncoding, any> ? TEncoding extends string ? ToBodyMime<TEncoding> : undefined : never;
+/**
+ * Infers the body type from a Payload and fallback type.
+ *
+ * @template TPayload - The Payload type
+ * @template TBody - Fallback body type for non-JSON encodings without schema
+ */
+export type InferPayloadBody<TPayload extends Payload, TBinary> = TPayload extends Payload<infer TEncoding, infer TSchema> ? TEncoding extends string ? ToBodyType<TEncoding, TSchema, TBinary> : undefined : never;
+/**
+ * Determines valid schema type based on encoding presence.
+ *
+ * @template E - The encoding string type, or undefined
+ */
+export type PayloadSchema<E extends string | undefined> = E extends undefined ? undefined : Schema<LexValue> | undefined;
+/**
+ * Represents a payload definition for Lexicon endpoints.
+ *
+ * Payloads define the body format for HTTP requests and responses.
+ * They consist of an encoding (MIME type) and an optional schema
+ * for validating the body content.
+ *
+ * @template TEncoding - The MIME type string, or undefined for no body
+ * @template TPayload - The schema type for body validation
+ *
+ * @example
+ * ```ts
+ * const jsonPayload = new Payload('application/json', l.object({ data: l.string() }))
+ * const binaryPayload = new Payload('image/*', undefined)
+ * const noPayload = new Payload(undefined, undefined)
+ * ```
+ */
+export declare class Payload<const TEncoding extends string | undefined = string | undefined, const TSchema extends PayloadSchema<TEncoding> = PayloadSchema<TEncoding>> {
     readonly encoding: TEncoding;
-    readonly schema: TPayload;
-    constructor(encoding: TEncoding, schema: TPayload);
+    readonly schema: TSchema;
+    constructor(encoding: TEncoding, schema: TSchema);
     /**
      * Checks whether the given content-type matches the expected payload schema's
      * encoding.
      */
     matchesEncoding(contentType: string | undefined): boolean;
 }
-export declare function payload<const E extends string | undefined = undefined, const S extends PayloadShape<E> = undefined>(encoding?: E, validator?: S): Payload<E, S>;
-export declare function jsonPayload<const P extends ObjectSchemaShape>(properties: P): Payload<'application/json', ObjectSchema<P>>;
+/**
+ * Creates a payload definition for Lexicon endpoint bodies.
+ *
+ * Defines the expected MIME type and optional validation schema for
+ * request or response bodies.
+ *
+ * @param encoding - MIME type string (e.g., 'application/json', 'image/*'), or undefined for no body
+ * @param validator - Optional schema for validating the body content. Must be undefined if encoding is undefined.
+ * @returns A new {@link Payload} instance
+ *
+ * @example
+ * ```ts
+ * // JSON payload with schema
+ * const output = l.payload('application/json', l.object({
+ *   posts: l.array(postSchema),
+ *   cursor: l.optional(l.string()),
+ * }))
+ *
+ * // Binary payload (no schema validation)
+ * const blobInput = l.payload('*\/*', undefined)
+ *
+ * // Image payload with wildcard
+ * const imageInput = l.payload('image/*', undefined)
+ *
+ * // No payload (for endpoints without body)
+ * const noBody = l.payload()
+ * ```
+ */
+export declare function payload<const E extends string | undefined = undefined, const S extends PayloadSchema<E> = undefined>(encoding?: E, validator?: S): Payload<E, S>;
+/**
+ * Creates a JSON payload with an object schema.
+ *
+ * Convenience function for the common case of JSON request/response bodies.
+ * Equivalent to `l.payload('application/json', l.object(properties))`.
+ *
+ * @param properties - Object mapping property names to validators
+ * @returns A new {@link Payload} instance with 'application/json' encoding
+ *
+ * @example
+ * ```ts
+ * // Query output
+ * const profileOutput = l.jsonPayload({
+ *   did: l.string({ format: 'did' }),
+ *   handle: l.string({ format: 'handle' }),
+ *   displayName: l.optional(l.string()),
+ * })
+ *
+ * // Procedure input
+ * const createPostInput = l.jsonPayload({
+ *   text: l.string({ maxGraphemes: 300 }),
+ *   createdAt: l.string({ format: 'datetime' }),
+ * })
+ * ```
+ */
+export declare function jsonPayload<P extends Record<string, Validator<undefined | LexValue>>>(properties: P): Payload<'application/json', ObjectSchema<P>>;
 //# sourceMappingURL=payload.d.ts.map

package/dist/schema/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/schema/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAU,MAAM,aAAa,CAAA;AAErE,MAAM,MAAM,YAAY,CACtB,QAAQ,SAAS,OAAO,EACxB,KAAK,IACH,QAAQ,CAAC,UAAU,CAAC,SAAS,MAAM,CAAC,SAAS,MAAM,GACnD;IACE,QAAQ,EAAE,4BAA4B,CAAC,CAAC,CAAC,CAAA;IACzC,IAAI,EAAE,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;CACxC,GACD,IAAI,GAAG,SAAS,CAAA;AAEpB,MAAM,MAAM,4BAA4B,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,KAAK,GACxE,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,MAAM,IAAI,GACrC,GAAG,CAAC,IAAI,MAAM,EAAE,GAChB,CAAC,CAAA;AAEP,MAAM,MAAM,oBAAoB,CAAC,QAAQ,SAAS,OAAO,IACvD,QAAQ,CAAC,UAAU,CAAC,SAAS,MAAM,GAC/B,4BAA4B,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,GAClD,SAAS,CAAA;AAEf,MAAM,MAAM,gBAAgB,CAC1B,QAAQ,SAAS,OAAO,EACxB,KAAK,IACH,QAAQ,CAAC,UAAU,CAAC,SAAS,SAAS,GACtC,SAAS,GACT,QAAQ,CAAC,QAAQ,CAAC,SAAS,MAAM,GAC/B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GACzB,QAAQ,CAAC,UAAU,CAAC,SAAS,kBAAkB,GAC7C,QAAQ,GACR,KAAK,CAAA;AAEb,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,IAAI,CAAC,SAAS,SAAS,GACxE,SAAS,GACT,MAAM,GAAG,SAAS,CAAA;AAEtB,qBAAa,OAAO,CAClB,KAAK,CAAC,SAAS,SAAS,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,EAC/D,KAAK,CAAC,QAAQ,SAAS,YAAY,CAAC,SAAS,CAAC,GAAG,YAAY,CAAC,SAAS,CAAC;IAGtE,QAAQ,CAAC,QAAQ,EAAE,SAAS;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ;gBADhB,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,QAAQ;IAO3B;;;OAGG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;CA6B1D;AAGD,wBAAgB,OAAO,CACrB,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,SAAS,GAAG,SAAS,EAC9C,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAC3C,QAAQ,GAAE,CAAkB,EAAE,SAAS,GAAE,CAAkB,iBAE5D;AAGD,wBAAgB,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,iBAAiB,EAC3D,UAAU,EAAE,CAAC,GACZ,OAAO,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAE9C"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/schema/payload.ts"],"names":[],"mappings":"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"}

package/dist/schema/payload.js

@@ -4,6 +4,23 @@ exports.Payload = void 0;
 exports.payload = payload;
 exports.jsonPayload = jsonPayload;
 const object_js_1 = require("./object.js");
+/**
+ * Represents a payload definition for Lexicon endpoints.
+ *
+ * Payloads define the body format for HTTP requests and responses.
+ * They consist of an encoding (MIME type) and an optional schema
+ * for validating the body content.
+ *
+ * @template TEncoding - The MIME type string, or undefined for no body
+ * @template TPayload - The schema type for body validation
+ *
+ * @example
+ * ```ts
+ * const jsonPayload = new Payload('application/json', l.object({ data: l.string() }))
+ * const binaryPayload = new Payload('image/*', undefined)
+ * const noPayload = new Payload(undefined, undefined)
+ * ```
+ */
 class Payload {
     encoding;
     schema;
@@ -19,20 +36,20 @@ class Payload {
      * encoding.
      */
     matchesEncoding(contentType) {
-        const mime = contentType?.split(';', 1)[0].trim();
         const { encoding } = this;
         // Handle undefined cases
         if (encoding === undefined) {
             // Expecting no body
-            return mime === undefined;
+            return contentType == null;
         }
-        else if (mime === undefined) {
+        else if (contentType == null) {
             // Expecting a body, but got no content-type
             return false;
         }
         if (encoding === '*/*') {
             return true;
         }
+        const mime = contentType?.split(';', 1)[0].trim();
         if (encoding.endsWith('/*')) {
             return mime.startsWith(encoding.slice(0, -1));
         }
@@ -44,10 +61,63 @@ class Payload {
     }
 }
 exports.Payload = Payload;
+/**
+ * Creates a payload definition for Lexicon endpoint bodies.
+ *
+ * Defines the expected MIME type and optional validation schema for
+ * request or response bodies.
+ *
+ * @param encoding - MIME type string (e.g., 'application/json', 'image/*'), or undefined for no body
+ * @param validator - Optional schema for validating the body content. Must be undefined if encoding is undefined.
+ * @returns A new {@link Payload} instance
+ *
+ * @example
+ * ```ts
+ * // JSON payload with schema
+ * const output = l.payload('application/json', l.object({
+ *   posts: l.array(postSchema),
+ *   cursor: l.optional(l.string()),
+ * }))
+ *
+ * // Binary payload (no schema validation)
+ * const blobInput = l.payload('*\/*', undefined)
+ *
+ * // Image payload with wildcard
+ * const imageInput = l.payload('image/*', undefined)
+ *
+ * // No payload (for endpoints without body)
+ * const noBody = l.payload()
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function payload(encoding = undefined, validator = undefined) {
     return new Payload(encoding, validator);
 }
+/**
+ * Creates a JSON payload with an object schema.
+ *
+ * Convenience function for the common case of JSON request/response bodies.
+ * Equivalent to `l.payload('application/json', l.object(properties))`.
+ *
+ * @param properties - Object mapping property names to validators
+ * @returns A new {@link Payload} instance with 'application/json' encoding
+ *
+ * @example
+ * ```ts
+ * // Query output
+ * const profileOutput = l.jsonPayload({
+ *   did: l.string({ format: 'did' }),
+ *   handle: l.string({ format: 'handle' }),
+ *   displayName: l.optional(l.string()),
+ * })
+ *
+ * // Procedure input
+ * const createPostInput = l.jsonPayload({
+ *   text: l.string({ maxGraphemes: 300 }),
+ *   createdAt: l.string({ format: 'datetime' }),
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function jsonPayload(properties) {
     return payload('application/json', (0, object_js_1.object)(properties));

package/dist/schema/payload.js.map

@@ -1 +1 @@
-{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/schema/payload.ts"],"names":[],"mappings":";;;AAyFA,0BAKC;AAGD,kCAIC;AAnGD,2CAAqE;AAsCrE,MAAa,OAAO;IAKP;IACA;IAFX,YACW,QAAmB,EACnB,MAAgB;QADhB,aAAQ,GAAR,QAAQ,CAAW;QACnB,WAAM,GAAN,MAAM,CAAU;QAEzB,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACnD,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAA;QAC5E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,WAA+B;QAC7C,MAAM,IAAI,GAAG,WAAW,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAEjD,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;QAEzB,yBAAyB;QACzB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,oBAAoB;YACpB,OAAO,IAAI,KAAK,SAAS,CAAA;QAC3B,CAAC;aAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,4CAA4C;YAC5C,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACvB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/C,CAAC;QAED,gEAAgE;QAChE,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,QAAQ,KAAK,IAAI,CAAA;IAC1B,CAAC;CACF;AA9CD,0BA8CC;AAED,wBAAwB;AACxB,SAAgB,OAAO,CAGrB,WAAc,SAAc,EAAE,YAAe,SAAc;IAC3D,OAAO,IAAI,OAAO,CAAO,QAAQ,EAAE,SAAS,CAAC,CAAA;AAC/C,CAAC;AAED,wBAAwB;AACxB,SAAgB,WAAW,CACzB,UAAa;IAEb,OAAO,OAAO,CAAC,kBAAkB,EAAE,IAAA,kBAAM,EAAC,UAAU,CAAC,CAAC,CAAA;AACxD,CAAC","sourcesContent":["import { LexValue } from '@atproto/lex-data'\nimport { Infer, Schema } from '../core.js'\nimport { ObjectSchema, ObjectSchemaShape, object } from './object.js'\n\nexport type InferPayload<\n  TPayload extends Payload,\n  TBody,\n> = TPayload['encoding'] extends infer E extends string\n  ? {\n      encoding: SchemaEncodingToDataEncoding<E>\n      body: InferPayloadBody<TPayload, TBody>\n    }\n  : void | undefined\n\nexport type SchemaEncodingToDataEncoding<E extends string> = E extends '*/*'\n  ? `${string}/${string}`\n  : E extends `${infer T extends string}/*`\n    ? `${T}/${string}`\n    : E\n\nexport type InferPayloadEncoding<TPayload extends Payload> =\n  TPayload['encoding'] extends string\n    ? SchemaEncodingToDataEncoding<TPayload['encoding']>\n    : undefined\n\nexport type InferPayloadBody<\n  TPayload extends Payload,\n  TBody,\n> = TPayload['encoding'] extends undefined\n  ? undefined // No encoding, no payload\n  : TPayload['schema'] extends Schema\n    ? Infer<TPayload['schema']>\n    : TPayload['encoding'] extends `application/json`\n      ? LexValue\n      : TBody\n\nexport type PayloadShape<E extends string | undefined> = E extends undefined\n  ? undefined\n  : Schema | undefined\n\nexport class Payload<\n  const TEncoding extends string | undefined = string | undefined,\n  const TPayload extends PayloadShape<TEncoding> = PayloadShape<TEncoding>,\n> {\n  constructor(\n    readonly encoding: TEncoding,\n    readonly schema: TPayload,\n  ) {\n    if (encoding === undefined && schema !== undefined) {\n      throw new TypeError('schema cannot be defined when encoding is undefined')\n    }\n  }\n\n  /**\n   * Checks whether the given content-type matches the expected payload schema's\n   * encoding.\n   */\n  matchesEncoding(contentType: string | undefined): boolean {\n    const mime = contentType?.split(';', 1)[0].trim()\n\n    const { encoding } = this\n\n    // Handle undefined cases\n    if (encoding === undefined) {\n      // Expecting no body\n      return mime === undefined\n    } else if (mime === undefined) {\n      // Expecting a body, but got no content-type\n      return false\n    }\n\n    if (encoding === '*/*') {\n      return true\n    }\n\n    if (encoding.endsWith('/*')) {\n      return mime.startsWith(encoding.slice(0, -1))\n    }\n\n    // Invalid: Lexicon can only specify \"*/*\" or \"type/*\" wildcards\n    if (encoding.includes('*')) {\n      return false\n    }\n\n    return encoding === mime\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function payload<\n  const E extends string | undefined = undefined,\n  const S extends PayloadShape<E> = undefined,\n>(encoding: E = undefined as E, validator: S = undefined as S) {\n  return new Payload<E, S>(encoding, validator)\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function jsonPayload<const P extends ObjectSchemaShape>(\n  properties: P,\n): Payload<'application/json', ObjectSchema<P>> {\n  return payload('application/json', object(properties))\n}\n"]}
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/schema/payload.ts"],"names":[],"mappings":";;;AAuKA,0BAKC;AA4BD,kCAIC;AA1MD,2CAAkD;AAwElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,OAAO;IAKP;IACA;IAFX,YACW,QAAmB,EACnB,MAAe;QADf,aAAQ,GAAR,QAAQ,CAAW;QACnB,WAAM,GAAN,MAAM,CAAS;QAExB,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACnD,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAA;QAC5E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,WAA+B;QAC7C,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;QAEzB,yBAAyB;QACzB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,oBAAoB;YACpB,OAAO,WAAW,IAAI,IAAI,CAAA;QAC5B,CAAC;aAAM,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;YAC/B,4CAA4C;YAC5C,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACvB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACjD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/C,CAAC;QAED,gEAAgE;QAChE,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,QAAQ,KAAK,IAAI,CAAA;IAC1B,CAAC;CACF;AA7CD,0BA6CC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAwB;AACxB,SAAgB,OAAO,CAGrB,WAAc,SAAc,EAAE,YAAe,SAAc;IAC3D,OAAO,IAAI,OAAO,CAAO,QAAQ,EAAE,SAAS,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAwB;AACxB,SAAgB,WAAW,CAEzB,UAAa;IACb,OAAO,OAAO,CAAC,kBAAkB,EAAE,IAAA,kBAAM,EAAC,UAAU,CAAC,CAAC,CAAA;AACxD,CAAC","sourcesContent":["import { LexValue } from '@atproto/lex-data'\nimport { Infer, Schema, Validator } from '../core.js'\nimport { ObjectSchema, object } from './object.js'\n\nexport type { LexValue }\n\ntype ToBodyMime<TEncoding extends string> = TEncoding extends '*/*'\n  ? `${string}/${string}`\n  : TEncoding extends `${infer T extends string}/*`\n    ? `${T}/${string}`\n    : TEncoding\n\ntype ToBodyType<\n  TEncoding extends string,\n  TSchema,\n  TBinary,\n> = TSchema extends Schema\n  ? Infer<TSchema>\n  : TEncoding extends `application/json`\n    ? LexValue\n    : TBinary\n\n/**\n * Infers the type of a Payload's encoding and body.\n *\n * @template TPayload - The Payload type\n * @template TBody - Fallback body type for non-JSON encodings\n */\nexport type InferPayload<TPayload extends Payload, TBinary> =\n  TPayload extends Payload<infer TEncoding, infer TSchema>\n    ? TEncoding extends string\n      ? {\n          encoding: ToBodyMime<TEncoding>\n          body: ToBodyType<TEncoding, TSchema, TBinary>\n        }\n      : undefined\n    : never\n\n/**\n * Converts schema encoding patterns to data encoding types.\n *\n * Handles wildcards like '*\\/*' and 'image/*' in MIME types.\n *\n * @template TPayload - The Payload type\n */\nexport type InferPayloadEncoding<TPayload extends Payload> =\n  TPayload extends Payload<infer TEncoding, any>\n    ? TEncoding extends string\n      ? ToBodyMime<TEncoding>\n      : undefined\n    : never\n\n/**\n * Infers the body type from a Payload and fallback type.\n *\n * @template TPayload - The Payload type\n * @template TBody - Fallback body type for non-JSON encodings without schema\n */\nexport type InferPayloadBody<TPayload extends Payload, TBinary> =\n  TPayload extends Payload<infer TEncoding, infer TSchema>\n    ? TEncoding extends string\n      ? ToBodyType<TEncoding, TSchema, TBinary>\n      : undefined\n    : never\n\n/**\n * Determines valid schema type based on encoding presence.\n *\n * @template E - The encoding string type, or undefined\n */\nexport type PayloadSchema<E extends string | undefined> = E extends undefined\n  ? undefined\n  : Schema<LexValue> | undefined\n\n/**\n * Represents a payload definition for Lexicon endpoints.\n *\n * Payloads define the body format for HTTP requests and responses.\n * They consist of an encoding (MIME type) and an optional schema\n * for validating the body content.\n *\n * @template TEncoding - The MIME type string, or undefined for no body\n * @template TPayload - The schema type for body validation\n *\n * @example\n * ```ts\n * const jsonPayload = new Payload('application/json', l.object({ data: l.string() }))\n * const binaryPayload = new Payload('image/*', undefined)\n * const noPayload = new Payload(undefined, undefined)\n * ```\n */\nexport class Payload<\n  const TEncoding extends string | undefined = string | undefined,\n  const TSchema extends PayloadSchema<TEncoding> = PayloadSchema<TEncoding>,\n> {\n  constructor(\n    readonly encoding: TEncoding,\n    readonly schema: TSchema,\n  ) {\n    if (encoding === undefined && schema !== undefined) {\n      throw new TypeError('schema cannot be defined when encoding is undefined')\n    }\n  }\n\n  /**\n   * Checks whether the given content-type matches the expected payload schema's\n   * encoding.\n   */\n  matchesEncoding(contentType: string | undefined): boolean {\n    const { encoding } = this\n\n    // Handle undefined cases\n    if (encoding === undefined) {\n      // Expecting no body\n      return contentType == null\n    } else if (contentType == null) {\n      // Expecting a body, but got no content-type\n      return false\n    }\n\n    if (encoding === '*/*') {\n      return true\n    }\n\n    const mime = contentType?.split(';', 1)[0].trim()\n    if (encoding.endsWith('/*')) {\n      return mime.startsWith(encoding.slice(0, -1))\n    }\n\n    // Invalid: Lexicon can only specify \"*/*\" or \"type/*\" wildcards\n    if (encoding.includes('*')) {\n      return false\n    }\n\n    return encoding === mime\n  }\n}\n\n/**\n * Creates a payload definition for Lexicon endpoint bodies.\n *\n * Defines the expected MIME type and optional validation schema for\n * request or response bodies.\n *\n * @param encoding - MIME type string (e.g., 'application/json', 'image/*'), or undefined for no body\n * @param validator - Optional schema for validating the body content. Must be undefined if encoding is undefined.\n * @returns A new {@link Payload} instance\n *\n * @example\n * ```ts\n * // JSON payload with schema\n * const output = l.payload('application/json', l.object({\n *   posts: l.array(postSchema),\n *   cursor: l.optional(l.string()),\n * }))\n *\n * // Binary payload (no schema validation)\n * const blobInput = l.payload('*\\/*', undefined)\n *\n * // Image payload with wildcard\n * const imageInput = l.payload('image/*', undefined)\n *\n * // No payload (for endpoints without body)\n * const noBody = l.payload()\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function payload<\n  const E extends string | undefined = undefined,\n  const S extends PayloadSchema<E> = undefined,\n>(encoding: E = undefined as E, validator: S = undefined as S) {\n  return new Payload<E, S>(encoding, validator)\n}\n\n/**\n * Creates a JSON payload with an object schema.\n *\n * Convenience function for the common case of JSON request/response bodies.\n * Equivalent to `l.payload('application/json', l.object(properties))`.\n *\n * @param properties - Object mapping property names to validators\n * @returns A new {@link Payload} instance with 'application/json' encoding\n *\n * @example\n * ```ts\n * // Query output\n * const profileOutput = l.jsonPayload({\n *   did: l.string({ format: 'did' }),\n *   handle: l.string({ format: 'handle' }),\n *   displayName: l.optional(l.string()),\n * })\n *\n * // Procedure input\n * const createPostInput = l.jsonPayload({\n *   text: l.string({ maxGraphemes: 300 }),\n *   createdAt: l.string({ format: 'datetime' }),\n * })\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function jsonPayload<\n  P extends Record<string, Validator<undefined | LexValue>>,\n>(properties: P): Payload<'application/json', ObjectSchema<P>> {\n  return payload('application/json', object(properties))\n}\n"]}

package/dist/schema/permission-set.d.ts

@@ -1,16 +1,74 @@
 import { NsidString } from '../core.js';
 import { Permission } from './permission.js';
+/**
+ * Configuration options for a permission set.
+ *
+ * @property title - Human-readable title for the permission set
+ * @property title:lang - Localized titles by language code
+ * @property detail - Detailed description of the permission set
+ * @property detail:lang - Localized descriptions by language code
+ */
 export type PermissionSetOptions = {
     title?: string;
     'title:lang'?: Record<string, undefined | string>;
     detail?: string;
     'detail:lang'?: Record<string, undefined | string>;
 };
+/**
+ * Represents a collection of related permissions in AT Protocol.
+ *
+ * Permission sets group permissions together with metadata for OAuth
+ * authorization flows. They are identified by an NSID.
+ *
+ * @template TNsid - The NSID identifying this permission set
+ * @template TPermissions - Tuple type of the included permissions
+ *
+ * @example
+ * ```ts
+ * const feedAccess = new PermissionSet(
+ *   'app.bsky.feed.access',
+ *   [readPermission, writePermission],
+ *   { title: 'Feed Access', detail: 'Read and write to your feed' }
+ * )
+ * ```
+ */
 export declare class PermissionSet<const TNsid extends NsidString = any, const TPermissions extends readonly Permission[] = any> {
     readonly nsid: TNsid;
     readonly permissions: TPermissions;
     readonly options: PermissionSetOptions;
     constructor(nsid: TNsid, permissions: TPermissions, options?: PermissionSetOptions);
 }
+/**
+ * Creates a permission set grouping related permissions.
+ *
+ * Permission sets define OAuth scopes that applications can request.
+ * They include human-readable metadata for authorization UIs.
+ *
+ * @param nsid - The NSID identifying this permission set
+ * @param permissions - Array of permissions included in this set
+ * @param options - Optional metadata (title, detail, localization)
+ * @returns A new {@link PermissionSet} instance
+ *
+ * @example
+ * ```ts
+ * // Define individual permissions
+ * const readPosts = l.permission('read', { collection: 'app.bsky.feed.post' })
+ * const writePosts = l.permission('write', { collection: 'app.bsky.feed.post' })
+ *
+ * // Group into a permission set
+ * const postManagement = l.permissionSet(
+ *   'app.bsky.feed.postManagement',
+ *   [readPosts, writePosts],
+ *   {
+ *     title: 'Post Management',
+ *     detail: 'View and create posts on your behalf',
+ *     'title:lang': {
+ *       'es': 'Gestion de publicaciones',
+ *       'fr': 'Gestion des publications',
+ *     },
+ *   }
+ * )
+ * ```
+ */
 export declare function permissionSet<const N extends NsidString, const P extends readonly Permission[]>(nsid: N, permissions: P, options?: PermissionSetOptions): PermissionSet<N, P>;
 //# sourceMappingURL=permission-set.d.ts.map

package/dist/schema/permission-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-set.d.ts","sourceRoot":"","sources":["../../src/schema/permission-set.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;CACnD,CAAA;AAED,qBAAa,aAAa,CACxB,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,EACpC,KAAK,CAAC,YAAY,SAAS,SAAS,UAAU,EAAE,GAAG,GAAG;IAGpD,QAAQ,CAAC,IAAI,EAAE,KAAK;IACpB,QAAQ,CAAC,WAAW,EAAE,YAAY;IAClC,QAAQ,CAAC,OAAO,EAAE,oBAAoB;gBAF7B,IAAI,EAAE,KAAK,EACX,WAAW,EAAE,YAAY,EACzB,OAAO,GAAE,oBAAyB;CAE9C;AAGD,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,EACrC,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,oBAAoB,uBAExD"}
+{"version":3,"file":"permission-set.d.ts","sourceRoot":"","sources":["../../src/schema/permission-set.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,CAAA;CACnD,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa,CACxB,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,EACpC,KAAK,CAAC,YAAY,SAAS,SAAS,UAAU,EAAE,GAAG,GAAG;IAGpD,QAAQ,CAAC,IAAI,EAAE,KAAK;IACpB,QAAQ,CAAC,WAAW,EAAE,YAAY;IAClC,QAAQ,CAAC,OAAO,EAAE,oBAAoB;gBAF7B,IAAI,EAAE,KAAK,EACX,WAAW,EAAE,YAAY,EACzB,OAAO,GAAE,oBAAyB;CAE9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,EACrC,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,oBAAoB,uBAExD"}

package/dist/schema/permission-set.js

@@ -2,6 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PermissionSet = void 0;
 exports.permissionSet = permissionSet;
+/**
+ * Represents a collection of related permissions in AT Protocol.
+ *
+ * Permission sets group permissions together with metadata for OAuth
+ * authorization flows. They are identified by an NSID.
+ *
+ * @template TNsid - The NSID identifying this permission set
+ * @template TPermissions - Tuple type of the included permissions
+ *
+ * @example
+ * ```ts
+ * const feedAccess = new PermissionSet(
+ *   'app.bsky.feed.access',
+ *   [readPermission, writePermission],
+ *   { title: 'Feed Access', detail: 'Read and write to your feed' }
+ * )
+ * ```
+ */
 class PermissionSet {
     nsid;
     permissions;
@@ -13,6 +31,38 @@ class PermissionSet {
     }
 }
 exports.PermissionSet = PermissionSet;
+/**
+ * Creates a permission set grouping related permissions.
+ *
+ * Permission sets define OAuth scopes that applications can request.
+ * They include human-readable metadata for authorization UIs.
+ *
+ * @param nsid - The NSID identifying this permission set
+ * @param permissions - Array of permissions included in this set
+ * @param options - Optional metadata (title, detail, localization)
+ * @returns A new {@link PermissionSet} instance
+ *
+ * @example
+ * ```ts
+ * // Define individual permissions
+ * const readPosts = l.permission('read', { collection: 'app.bsky.feed.post' })
+ * const writePosts = l.permission('write', { collection: 'app.bsky.feed.post' })
+ *
+ * // Group into a permission set
+ * const postManagement = l.permissionSet(
+ *   'app.bsky.feed.postManagement',
+ *   [readPosts, writePosts],
+ *   {
+ *     title: 'Post Management',
+ *     detail: 'View and create posts on your behalf',
+ *     'title:lang': {
+ *       'es': 'Gestion de publicaciones',
+ *       'fr': 'Gestion des publications',
+ *     },
+ *   }
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function permissionSet(nsid, permissions, options) {
     return new PermissionSet(nsid, permissions, options);

package/dist/schema/permission-set.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission-set.js","sourceRoot":"","sources":["../../src/schema/permission-set.ts"],"names":[],"mappings":";;;AAsBA,sCAKC;AAjBD,MAAa,aAAa;IAKb;IACA;IACA;IAHX,YACW,IAAW,EACX,WAAyB,EACzB,UAAgC,EAAE;QAFlC,SAAI,GAAJ,IAAI,CAAO;QACX,gBAAW,GAAX,WAAW,CAAc;QACzB,YAAO,GAAP,OAAO,CAA2B;IAC1C,CAAC;CACL;AATD,sCASC;AAED,wBAAwB;AACxB,SAAgB,aAAa,CAG3B,IAAO,EAAE,WAAc,EAAE,OAA8B;IACvD,OAAO,IAAI,aAAa,CAAO,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;AAC5D,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { Permission } from './permission.js'\n\nexport type PermissionSetOptions = {\n  title?: string\n  'title:lang'?: Record<string, undefined | string>\n  detail?: string\n  'detail:lang'?: Record<string, undefined | string>\n}\n\nexport class PermissionSet<\n  const TNsid extends NsidString = any,\n  const TPermissions extends readonly Permission[] = any,\n> {\n  constructor(\n    readonly nsid: TNsid,\n    readonly permissions: TPermissions,\n    readonly options: PermissionSetOptions = {},\n  ) {}\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function permissionSet<\n  const N extends NsidString,\n  const P extends readonly Permission[],\n>(nsid: N, permissions: P, options?: PermissionSetOptions) {\n  return new PermissionSet<N, P>(nsid, permissions, options)\n}\n"]}
+{"version":3,"file":"permission-set.js","sourceRoot":"","sources":["../../src/schema/permission-set.ts"],"names":[],"mappings":";;;AAgFA,sCAKC;AAnED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,aAAa;IAKb;IACA;IACA;IAHX,YACW,IAAW,EACX,WAAyB,EACzB,UAAgC,EAAE;QAFlC,SAAI,GAAJ,IAAI,CAAO;QACX,gBAAW,GAAX,WAAW,CAAc;QACzB,YAAO,GAAP,OAAO,CAA2B;IAC1C,CAAC;CACL;AATD,sCASC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAwB;AACxB,SAAgB,aAAa,CAG3B,IAAO,EAAE,WAAc,EAAE,OAA8B;IACvD,OAAO,IAAI,aAAa,CAAO,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAA;AAC5D,CAAC","sourcesContent":["import { NsidString } from '../core.js'\nimport { Permission } from './permission.js'\n\n/**\n * Configuration options for a permission set.\n *\n * @property title - Human-readable title for the permission set\n * @property title:lang - Localized titles by language code\n * @property detail - Detailed description of the permission set\n * @property detail:lang - Localized descriptions by language code\n */\nexport type PermissionSetOptions = {\n  title?: string\n  'title:lang'?: Record<string, undefined | string>\n  detail?: string\n  'detail:lang'?: Record<string, undefined | string>\n}\n\n/**\n * Represents a collection of related permissions in AT Protocol.\n *\n * Permission sets group permissions together with metadata for OAuth\n * authorization flows. They are identified by an NSID.\n *\n * @template TNsid - The NSID identifying this permission set\n * @template TPermissions - Tuple type of the included permissions\n *\n * @example\n * ```ts\n * const feedAccess = new PermissionSet(\n *   'app.bsky.feed.access',\n *   [readPermission, writePermission],\n *   { title: 'Feed Access', detail: 'Read and write to your feed' }\n * )\n * ```\n */\nexport class PermissionSet<\n  const TNsid extends NsidString = any,\n  const TPermissions extends readonly Permission[] = any,\n> {\n  constructor(\n    readonly nsid: TNsid,\n    readonly permissions: TPermissions,\n    readonly options: PermissionSetOptions = {},\n  ) {}\n}\n\n/**\n * Creates a permission set grouping related permissions.\n *\n * Permission sets define OAuth scopes that applications can request.\n * They include human-readable metadata for authorization UIs.\n *\n * @param nsid - The NSID identifying this permission set\n * @param permissions - Array of permissions included in this set\n * @param options - Optional metadata (title, detail, localization)\n * @returns A new {@link PermissionSet} instance\n *\n * @example\n * ```ts\n * // Define individual permissions\n * const readPosts = l.permission('read', { collection: 'app.bsky.feed.post' })\n * const writePosts = l.permission('write', { collection: 'app.bsky.feed.post' })\n *\n * // Group into a permission set\n * const postManagement = l.permissionSet(\n *   'app.bsky.feed.postManagement',\n *   [readPosts, writePosts],\n *   {\n *     title: 'Post Management',\n *     detail: 'View and create posts on your behalf',\n *     'title:lang': {\n *       'es': 'Gestion de publicaciones',\n *       'fr': 'Gestion des publications',\n *     },\n *   }\n * )\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function permissionSet<\n  const N extends NsidString,\n  const P extends readonly Permission[],\n>(nsid: N, permissions: P, options?: PermissionSetOptions) {\n  return new PermissionSet<N, P>(nsid, permissions, options)\n}\n"]}

package/dist/schema/permission.d.ts

@@ -1,9 +1,51 @@
 import { Params } from './params.js';
+/**
+ * Type alias for permission options (same as Params).
+ */
 export type PermissionOptions = Params;
+/**
+ * Represents a single permission in an AT Protocol permission set.
+ *
+ * Permissions define access rights to specific resources with optional
+ * parameters for fine-grained control.
+ *
+ * @template TResource - The resource identifier string type
+ * @template TOptions - The options type (must be valid Params)
+ *
+ * @example
+ * ```ts
+ * const readPermission = new Permission('read', { collection: 'app.bsky.feed.post' })
+ * ```
+ */
 export declare class Permission<const TResource extends string = any, const TOptions extends PermissionOptions = any> {
     readonly resource: TResource;
     readonly options: TOptions;
     constructor(resource: TResource, options: TOptions);
 }
+/**
+ * Creates a permission definition for AT Protocol authorization.
+ *
+ * Permissions specify what resources an application can access.
+ * Used in permission sets to define OAuth scopes.
+ *
+ * @param resource - The resource identifier (e.g., 'read', 'write', 'admin')
+ * @param options - Optional parameters for the permission
+ * @returns A new {@link Permission} instance
+ *
+ * @example
+ * ```ts
+ * // Simple permission
+ * const readPermission = l.permission('read')
+ *
+ * // Permission with options
+ * const writePostsPermission = l.permission('write', {
+ *   collection: 'app.bsky.feed.post',
+ * })
+ *
+ * // Multiple permissions with different scopes
+ * const readProfile = l.permission('read', { collection: 'app.bsky.actor.profile' })
+ * const readFeed = l.permission('read', { collection: 'app.bsky.feed.*' })
+ * ```
+ */
 export declare function permission<const R extends string, const O extends PermissionOptions>(resource: R, options?: PermissionOptions & O): Permission<R, O>;
 //# sourceMappingURL=permission.d.ts.map

package/dist/schema/permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/schema/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAA;AAEtC,qBAAa,UAAU,CACrB,KAAK,CAAC,SAAS,SAAS,MAAM,GAAG,GAAG,EACpC,KAAK,CAAC,QAAQ,SAAS,iBAAiB,GAAG,GAAG;IAG5C,QAAQ,CAAC,QAAQ,EAAE,SAAS;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ;gBADjB,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ;CAE7B;AAGD,wBAAgB,UAAU,CACxB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,KAAK,CAAC,CAAC,SAAS,iBAAiB,EACjC,QAAQ,EAAE,CAAC,EAAE,OAAO,GAAE,iBAAiB,GAAG,CAAW,oBAEtD"}
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../../src/schema/permission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAA;AAEtC;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU,CACrB,KAAK,CAAC,SAAS,SAAS,MAAM,GAAG,GAAG,EACpC,KAAK,CAAC,QAAQ,SAAS,iBAAiB,GAAG,GAAG;IAG5C,QAAQ,CAAC,QAAQ,EAAE,SAAS;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ;gBADjB,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ;CAE7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAgB,UAAU,CACxB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,KAAK,CAAC,CAAC,SAAS,iBAAiB,EACjC,QAAQ,EAAE,CAAC,EAAE,OAAO,GAAE,iBAAiB,GAAG,CAAW,oBAEtD"}

package/dist/schema/permission.js

@@ -2,6 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Permission = void 0;
 exports.permission = permission;
+/**
+ * Represents a single permission in an AT Protocol permission set.
+ *
+ * Permissions define access rights to specific resources with optional
+ * parameters for fine-grained control.
+ *
+ * @template TResource - The resource identifier string type
+ * @template TOptions - The options type (must be valid Params)
+ *
+ * @example
+ * ```ts
+ * const readPermission = new Permission('read', { collection: 'app.bsky.feed.post' })
+ * ```
+ */
 class Permission {
     resource;
     options;
@@ -11,6 +25,31 @@ class Permission {
     }
 }
 exports.Permission = Permission;
+/**
+ * Creates a permission definition for AT Protocol authorization.
+ *
+ * Permissions specify what resources an application can access.
+ * Used in permission sets to define OAuth scopes.
+ *
+ * @param resource - The resource identifier (e.g., 'read', 'write', 'admin')
+ * @param options - Optional parameters for the permission
+ * @returns A new {@link Permission} instance
+ *
+ * @example
+ * ```ts
+ * // Simple permission
+ * const readPermission = l.permission('read')
+ *
+ * // Permission with options
+ * const writePostsPermission = l.permission('write', {
+ *   collection: 'app.bsky.feed.post',
+ * })
+ *
+ * // Multiple permissions with different scopes
+ * const readProfile = l.permission('read', { collection: 'app.bsky.actor.profile' })
+ * const readFeed = l.permission('read', { collection: 'app.bsky.feed.*' })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function permission(resource, options = {}) {
     return new Permission(resource, options);

package/dist/schema/permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/schema/permission.ts"],"names":[],"mappings":";;;AAeA,gCAKC;AAhBD,MAAa,UAAU;IAKV;IACA;IAFX,YACW,QAAmB,EACnB,OAAiB;QADjB,aAAQ,GAAR,QAAQ,CAAW;QACnB,YAAO,GAAP,OAAO,CAAU;IACzB,CAAC;CACL;AARD,gCAQC;AAED,wBAAwB;AACxB,SAAgB,UAAU,CAGxB,QAAW,EAAE,UAAiC,EAAO;IACrD,OAAO,IAAI,UAAU,CAAO,QAAQ,EAAE,OAAO,CAAC,CAAA;AAChD,CAAC","sourcesContent":["import { Params } from './params.js'\n\nexport type PermissionOptions = Params\n\nexport class Permission<\n  const TResource extends string = any,\n  const TOptions extends PermissionOptions = any,\n> {\n  constructor(\n    readonly resource: TResource,\n    readonly options: TOptions,\n  ) {}\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function permission<\n  const R extends string,\n  const O extends PermissionOptions,\n>(resource: R, options: PermissionOptions & O = {} as O) {\n  return new Permission<R, O>(resource, options)\n}\n"]}
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/schema/permission.ts"],"names":[],"mappings":";;;AAyDA,gCAKC;AAvDD;;;;;;;;;;;;;GAaG;AACH,MAAa,UAAU;IAKV;IACA;IAFX,YACW,QAAmB,EACnB,OAAiB;QADjB,aAAQ,GAAR,QAAQ,CAAW;QACnB,YAAO,GAAP,OAAO,CAAU;IACzB,CAAC;CACL;AARD,gCAQC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAwB;AACxB,SAAgB,UAAU,CAGxB,QAAW,EAAE,UAAiC,EAAO;IACrD,OAAO,IAAI,UAAU,CAAO,QAAQ,EAAE,OAAO,CAAC,CAAA;AAChD,CAAC","sourcesContent":["import { Params } from './params.js'\n\n/**\n * Type alias for permission options (same as Params).\n */\nexport type PermissionOptions = Params\n\n/**\n * Represents a single permission in an AT Protocol permission set.\n *\n * Permissions define access rights to specific resources with optional\n * parameters for fine-grained control.\n *\n * @template TResource - The resource identifier string type\n * @template TOptions - The options type (must be valid Params)\n *\n * @example\n * ```ts\n * const readPermission = new Permission('read', { collection: 'app.bsky.feed.post' })\n * ```\n */\nexport class Permission<\n  const TResource extends string = any,\n  const TOptions extends PermissionOptions = any,\n> {\n  constructor(\n    readonly resource: TResource,\n    readonly options: TOptions,\n  ) {}\n}\n\n/**\n * Creates a permission definition for AT Protocol authorization.\n *\n * Permissions specify what resources an application can access.\n * Used in permission sets to define OAuth scopes.\n *\n * @param resource - The resource identifier (e.g., 'read', 'write', 'admin')\n * @param options - Optional parameters for the permission\n * @returns A new {@link Permission} instance\n *\n * @example\n * ```ts\n * // Simple permission\n * const readPermission = l.permission('read')\n *\n * // Permission with options\n * const writePostsPermission = l.permission('write', {\n *   collection: 'app.bsky.feed.post',\n * })\n *\n * // Multiple permissions with different scopes\n * const readProfile = l.permission('read', { collection: 'app.bsky.actor.profile' })\n * const readFeed = l.permission('read', { collection: 'app.bsky.feed.*' })\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function permission<\n  const R extends string,\n  const O extends PermissionOptions,\n>(resource: R, options: PermissionOptions & O = {} as O) {\n  return new Permission<R, O>(resource, options)\n}\n"]}