@itm-studio/partner-sdk 0.1.7 → 0.2.0

package/README.md

@@ -291,6 +291,205 @@ const { getPartnerPublicEchoes } = await itm.query({
 
 **Third-party embed types:** `SPOTIFY` | `INSTAGRAM` | `TIKTOK` — use `thirdPartyEchoType` and `thirdPartyEchoConfig` for embed details.
 
+## Available Mutations
+
+The SDK supports write operations via `client.mutation()`. All mutations use the same authentication — your brand is determined from the token.
+
+### Media Upload Flow
+
+Uploading media (e.g. cover images) is a two-step process:
+
+#### Step 1: `getPartnerUploadUrl`
+
+Get a presigned S3 URL to upload a file directly.
+
+```typescript
+const { getPartnerUploadUrl } = await itm.mutation({
+  getPartnerUploadUrl: {
+    __args: { filename: 'event-cover', fileExtension: 'jpg' },
+    url: true,
+    filename: true,
+  },
+});
+
+// Upload the file to S3 using the presigned URL
+await fetch(getPartnerUploadUrl.url, {
+  method: 'PUT',
+  body: fileBuffer, // Buffer, Blob, or ReadableStream
+  headers: { 'Content-Type': 'image/jpeg' },
+});
+```
+
+#### Step 2: `createPartnerMediaAsset`
+
+After uploading, register the asset so it's linked to your brand.
+
+```typescript
+const { createPartnerMediaAsset } = await itm.mutation({
+  createPartnerMediaAsset: {
+    __args: {
+      mimetype: 'image/jpeg',
+      filename: getPartnerUploadUrl.filename, // from Step 1
+      dimensions: { width: 1920, height: 1080 },
+    },
+    uid: true,
+    url: true,
+    mimeType: true,
+  },
+});
+
+// Use createPartnerMediaAsset.uid as coverImageUid when creating a moment
+```
+
+### `createPartnerMoment`
+
+Create a moment (event) with optional venue and ticket tiers in one atomic operation.
+
+```typescript
+const { createPartnerMoment } = await itm.mutation({
+  createPartnerMoment: {
+    __args: {
+      input: {
+        name: 'Summer Rooftop Party',
+        description: 'A rooftop party in NYC',
+        blurb: 'Join us on the roof!',
+        startDate: '2026-07-15T20:00:00.000Z',
+        endDate: '2026-07-16T02:00:00.000Z',
+        timezone: 'America/New_York',
+        type: 'IRL',
+        coverImageUid: createPartnerMediaAsset.uid, // from upload flow
+        venue: {
+          name: 'Rooftop Bar',
+          city: 'New York',
+          country: 'US',
+          address: '123 Main St',
+        },
+        category: 'PARTY',
+        subcategory: 'ROOFTOP_PARTY',
+        ticketTiers: [
+          {
+            name: 'General Admission',
+            price: 2500,          // $25.00 in cents
+            supply: 200,
+            maxPerUser: 4,
+            currencyCode: 'USD',
+          },
+          {
+            name: 'VIP',
+            price: 7500,          // $75.00 in cents
+            supply: 50,
+            maxPerUser: 2,
+            currencyCode: 'USD',
+            description: 'Includes open bar',
+          },
+        ],
+      },
+    },
+    uid: true,
+    name: true,
+    slug: true,
+    startDate: true,
+    endDate: true,
+    status: true,
+    coverImage: { url: true },
+    venue: { name: true, city: true },
+    ticketTiers: {
+      uid: true,
+      name: true,
+      price: true,
+      currency: { code: true, symbol: true },
+      soldOut: true,
+    },
+  },
+});
+```
+
+**Required fields:** `name`, `description`, `blurb`, `startDate`, `endDate`, `timezone`, `type`
+
+**Moment types:**
+- `IRL` — in-person event (requires `venue`)
+- `DIGITAL` — online event (no venue needed)
+
+**Ticket tier pricing:** `price` is in **cents** (e.g. `2500` = $25.00). Use `0` for free tiers.
+
+### Complete Upload + Create Moment Flow
+
+```typescript
+import { createITMPartnerClient } from '@itm-studio/partner-sdk';
+import { readFile } from 'fs/promises';
+
+const itm = createITMPartnerClient({
+  token: process.env.ITM_PARTNER_TOKEN!,
+});
+
+// 1. Get presigned upload URL
+const { getPartnerUploadUrl } = await itm.mutation({
+  getPartnerUploadUrl: {
+    __args: { filename: 'event-cover', fileExtension: 'jpg' },
+    url: true,
+    filename: true,
+  },
+});
+
+// 2. Upload file to S3
+const file = await readFile('./event-cover.jpg');
+await fetch(getPartnerUploadUrl.url, {
+  method: 'PUT',
+  body: file,
+  headers: { 'Content-Type': 'image/jpeg' },
+});
+
+// 3. Register the uploaded asset
+const { createPartnerMediaAsset } = await itm.mutation({
+  createPartnerMediaAsset: {
+    __args: {
+      mimetype: 'image/jpeg',
+      filename: getPartnerUploadUrl.filename,
+      dimensions: { width: 1920, height: 1080 },
+    },
+    uid: true,
+  },
+});
+
+// 4. Create the moment with the uploaded cover image
+const { createPartnerMoment } = await itm.mutation({
+  createPartnerMoment: {
+    __args: {
+      input: {
+        name: 'My Event',
+        description: 'An amazing event',
+        blurb: 'Come join us!',
+        startDate: '2026-07-15T20:00:00.000Z',
+        endDate: '2026-07-16T02:00:00.000Z',
+        timezone: 'America/New_York',
+        type: 'IRL',
+        coverImageUid: createPartnerMediaAsset.uid,
+        venue: {
+          name: 'The Venue',
+          city: 'New York',
+          country: 'US',
+        },
+        ticketTiers: [
+          {
+            name: 'General Admission',
+            price: 2500,
+            supply: 100,
+            maxPerUser: 4,
+            currencyCode: 'USD',
+          },
+        ],
+      },
+    },
+    uid: true,
+    slug: true,
+    status: true,
+    ticketTiers: { uid: true, name: true },
+  },
+});
+
+console.log(`Created: ${createPartnerMoment.slug} (${createPartnerMoment.status})`);
+```
+
 ## Pagination
 
 All list endpoints use cursor-based pagination. The default page size is **50** items if `take` is not specified.

package/dist/index.d.mts

@@ -285,6 +285,54 @@ interface Query {
     getPartnerPublicEchoes: GetBrandEchoesForUserResponse;
     __typename: 'Query';
 }
+/**
+ * A presigned S3 upload URL and the generated filename.
+ * Returned by getPartnerUploadUrl.
+ */
+interface MediaAssetUploadUrl {
+    /** Presigned S3 URL. PUT your file here. */
+    url: Scalars['String'];
+    /** Generated filename to pass to createPartnerMediaAsset after upload. */
+    filename: Scalars['String'];
+    __typename: 'MediaAssetUploadUrl';
+}
+/**
+ * A media asset uploaded by a partner.
+ * Returned by createPartnerMediaAsset.
+ */
+interface MediaAsset {
+    uid: Scalars['ID'];
+    /** CloudFront URL of the asset. */
+    url: Scalars['String'];
+    mimeType: Scalars['String'];
+    s3Key: Scalars['String'];
+    dimensions: Dimensions;
+    /** File size in bytes. */
+    size: Scalars['Int'];
+    placeholderUrl: (Scalars['String'] | null);
+    blurhash: (Scalars['String'] | null);
+    createdAt: Scalars['DateTime'];
+    updatedAt: Scalars['DateTime'];
+    __typename: 'MediaAsset';
+}
+interface Mutation {
+    /**
+     * Get a presigned S3 URL for direct file upload.
+     * Rate limited to 30 requests per minute.
+     */
+    getPartnerUploadUrl: MediaAssetUploadUrl;
+    /**
+     * Record an uploaded media asset and link it to the partner's brand.
+     * Call after uploading to S3 via the presigned URL from getPartnerUploadUrl.
+     */
+    createPartnerMediaAsset: MediaAsset;
+    /**
+     * Create a moment with optional venue and ticket tiers in one atomic operation.
+     * When type is IRL, the venue field is required.
+     */
+    createPartnerMoment: Moment;
+    __typename: 'Mutation';
+}
 interface CurrencyGenqlSelection {
     uid?: boolean | number;
     code?: boolean | number;
@@ -614,6 +662,123 @@ interface QueryGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface DimensionsInput {
+    width: Scalars['Int'];
+    height: Scalars['Int'];
+}
+interface VenueInput {
+    name: Scalars['String'];
+    city: Scalars['String'];
+    country: Scalars['String'];
+    address?: (Scalars['String'] | null);
+    postalCode?: (Scalars['String'] | null);
+}
+interface CreatePartnerTicketTierInput {
+    /** Name of the ticket tier (e.g. "General Admission", "VIP"). */
+    name: Scalars['String'];
+    /** Price in cents (0 for free). E.g. 2500 = $25.00. */
+    price: Scalars['Int'];
+    /** Total number of tickets available. */
+    supply: Scalars['Int'];
+    /** Maximum tickets per user (1-50). */
+    maxPerUser: Scalars['Int'];
+    /** ISO 4217 currency code (e.g. "USD", "GBP", "EUR"). */
+    currencyCode: Scalars['String'];
+    description?: (Scalars['String'] | null);
+    /** Minimum tickets per user (default: 1). */
+    minPerUser?: (Scalars['Int'] | null);
+    /** Default: false. */
+    isPrivate?: (Scalars['Boolean'] | null);
+    /** Default: true. */
+    isActive?: (Scalars['Boolean'] | null);
+}
+interface CreatePartnerMomentInput {
+    name: Scalars['String'];
+    description: Scalars['String'];
+    blurb: Scalars['String'];
+    startDate: Scalars['DateTime'];
+    endDate: Scalars['DateTime'];
+    /** IANA timezone (e.g. "America/New_York"). */
+    timezone: Scalars['String'];
+    /** IRL (in-person) or DIGITAL. */
+    type: MomentType;
+    /** UID of a previously uploaded media asset. If omitted, uses the brand default cover image. */
+    coverImageUid?: (Scalars['String'] | null);
+    /** Required when type is IRL. */
+    venue?: (VenueInput | null);
+    /** Default: false. */
+    isPrivate?: (Scalars['Boolean'] | null);
+    category?: (MomentCategory | null);
+    subcategory?: (MomentSubcategory | null);
+    /** Ticket tiers to create along with the moment. */
+    ticketTiers?: (CreatePartnerTicketTierInput[] | null);
+}
+/**
+ * A presigned S3 upload URL and the generated filename.
+ * Returned by getPartnerUploadUrl.
+ */
+interface MediaAssetUploadUrlGenqlSelection {
+    /** Presigned S3 URL. PUT your file here. */
+    url?: boolean | number;
+    /** Generated filename to pass to createPartnerMediaAsset after upload. */
+    filename?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+/**
+ * A media asset uploaded by a partner.
+ * Returned by createPartnerMediaAsset.
+ */
+interface MediaAssetGenqlSelection {
+    uid?: boolean | number;
+    /** CloudFront URL of the asset. */
+    url?: boolean | number;
+    mimeType?: boolean | number;
+    s3Key?: boolean | number;
+    dimensions?: DimensionsGenqlSelection;
+    /** File size in bytes. */
+    size?: boolean | number;
+    placeholderUrl?: boolean | number;
+    blurhash?: boolean | number;
+    createdAt?: boolean | number;
+    updatedAt?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+interface MutationGenqlSelection {
+    /**
+     * Get a presigned S3 URL for direct file upload.
+     * Rate limited to 30 requests per minute.
+     */
+    getPartnerUploadUrl?: (MediaAssetUploadUrlGenqlSelection & {
+        __args: {
+            filename: Scalars['String'];
+            fileExtension: Scalars['String'];
+        };
+    });
+    /**
+     * Record an uploaded media asset and link it to the partner's brand.
+     * Call after uploading to S3 via the presigned URL from getPartnerUploadUrl.
+     */
+    createPartnerMediaAsset?: (MediaAssetGenqlSelection & {
+        __args: {
+            mimetype: Scalars['String'];
+            filename: Scalars['String'];
+            dimensions: DimensionsInput;
+        };
+    });
+    /**
+     * Create a moment with optional venue and ticket tiers in one atomic operation.
+     * When type is IRL, the venue field is required.
+     */
+    createPartnerMoment?: (MomentGenqlSelection & {
+        __args: {
+            input: CreatePartnerMomentInput;
+        };
+    });
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 
 interface GraphqlOperation {
     query: string;
@@ -655,6 +820,9 @@ interface Client {
     query<R extends QueryGenqlSelection>(request: R & {
         __name?: string;
     }): Promise<FieldsSelection<Query, R>>;
+    mutation<R extends MutationGenqlSelection>(request: R & {
+        __name?: string;
+    }): Promise<FieldsSelection<Mutation, R>>;
 }
 declare const everything: {
     __scalar: boolean;
@@ -662,6 +830,9 @@ declare const everything: {
 declare const generateQueryOp: (fields: QueryGenqlSelection & {
     __name?: string;
 }) => GraphqlOperation;
+declare const generateMutationOp: (fields: MutationGenqlSelection & {
+    __name?: string;
+}) => GraphqlOperation;
 
 interface ITMPartnerClientConfig {
     /**
@@ -710,4 +881,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type Currency, type Dimensions, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type PartnerCustomer, type Payment, type PaymentStatus, type Query, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, createITMPartnerClient, everything, generateQueryOp };
+export { type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type Payment, type PaymentStatus, type Query, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };

package/dist/index.d.ts

@@ -285,6 +285,54 @@ interface Query {
     getPartnerPublicEchoes: GetBrandEchoesForUserResponse;
     __typename: 'Query';
 }
+/**
+ * A presigned S3 upload URL and the generated filename.
+ * Returned by getPartnerUploadUrl.
+ */
+interface MediaAssetUploadUrl {
+    /** Presigned S3 URL. PUT your file here. */
+    url: Scalars['String'];
+    /** Generated filename to pass to createPartnerMediaAsset after upload. */
+    filename: Scalars['String'];
+    __typename: 'MediaAssetUploadUrl';
+}
+/**
+ * A media asset uploaded by a partner.
+ * Returned by createPartnerMediaAsset.
+ */
+interface MediaAsset {
+    uid: Scalars['ID'];
+    /** CloudFront URL of the asset. */
+    url: Scalars['String'];
+    mimeType: Scalars['String'];
+    s3Key: Scalars['String'];
+    dimensions: Dimensions;
+    /** File size in bytes. */
+    size: Scalars['Int'];
+    placeholderUrl: (Scalars['String'] | null);
+    blurhash: (Scalars['String'] | null);
+    createdAt: Scalars['DateTime'];
+    updatedAt: Scalars['DateTime'];
+    __typename: 'MediaAsset';
+}
+interface Mutation {
+    /**
+     * Get a presigned S3 URL for direct file upload.
+     * Rate limited to 30 requests per minute.
+     */
+    getPartnerUploadUrl: MediaAssetUploadUrl;
+    /**
+     * Record an uploaded media asset and link it to the partner's brand.
+     * Call after uploading to S3 via the presigned URL from getPartnerUploadUrl.
+     */
+    createPartnerMediaAsset: MediaAsset;
+    /**
+     * Create a moment with optional venue and ticket tiers in one atomic operation.
+     * When type is IRL, the venue field is required.
+     */
+    createPartnerMoment: Moment;
+    __typename: 'Mutation';
+}
 interface CurrencyGenqlSelection {
     uid?: boolean | number;
     code?: boolean | number;
@@ -614,6 +662,123 @@ interface QueryGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface DimensionsInput {
+    width: Scalars['Int'];
+    height: Scalars['Int'];
+}
+interface VenueInput {
+    name: Scalars['String'];
+    city: Scalars['String'];
+    country: Scalars['String'];
+    address?: (Scalars['String'] | null);
+    postalCode?: (Scalars['String'] | null);
+}
+interface CreatePartnerTicketTierInput {
+    /** Name of the ticket tier (e.g. "General Admission", "VIP"). */
+    name: Scalars['String'];
+    /** Price in cents (0 for free). E.g. 2500 = $25.00. */
+    price: Scalars['Int'];
+    /** Total number of tickets available. */
+    supply: Scalars['Int'];
+    /** Maximum tickets per user (1-50). */
+    maxPerUser: Scalars['Int'];
+    /** ISO 4217 currency code (e.g. "USD", "GBP", "EUR"). */
+    currencyCode: Scalars['String'];
+    description?: (Scalars['String'] | null);
+    /** Minimum tickets per user (default: 1). */
+    minPerUser?: (Scalars['Int'] | null);
+    /** Default: false. */
+    isPrivate?: (Scalars['Boolean'] | null);
+    /** Default: true. */
+    isActive?: (Scalars['Boolean'] | null);
+}
+interface CreatePartnerMomentInput {
+    name: Scalars['String'];
+    description: Scalars['String'];
+    blurb: Scalars['String'];
+    startDate: Scalars['DateTime'];
+    endDate: Scalars['DateTime'];
+    /** IANA timezone (e.g. "America/New_York"). */
+    timezone: Scalars['String'];
+    /** IRL (in-person) or DIGITAL. */
+    type: MomentType;
+    /** UID of a previously uploaded media asset. If omitted, uses the brand default cover image. */
+    coverImageUid?: (Scalars['String'] | null);
+    /** Required when type is IRL. */
+    venue?: (VenueInput | null);
+    /** Default: false. */
+    isPrivate?: (Scalars['Boolean'] | null);
+    category?: (MomentCategory | null);
+    subcategory?: (MomentSubcategory | null);
+    /** Ticket tiers to create along with the moment. */
+    ticketTiers?: (CreatePartnerTicketTierInput[] | null);
+}
+/**
+ * A presigned S3 upload URL and the generated filename.
+ * Returned by getPartnerUploadUrl.
+ */
+interface MediaAssetUploadUrlGenqlSelection {
+    /** Presigned S3 URL. PUT your file here. */
+    url?: boolean | number;
+    /** Generated filename to pass to createPartnerMediaAsset after upload. */
+    filename?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+/**
+ * A media asset uploaded by a partner.
+ * Returned by createPartnerMediaAsset.
+ */
+interface MediaAssetGenqlSelection {
+    uid?: boolean | number;
+    /** CloudFront URL of the asset. */
+    url?: boolean | number;
+    mimeType?: boolean | number;
+    s3Key?: boolean | number;
+    dimensions?: DimensionsGenqlSelection;
+    /** File size in bytes. */
+    size?: boolean | number;
+    placeholderUrl?: boolean | number;
+    blurhash?: boolean | number;
+    createdAt?: boolean | number;
+    updatedAt?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+interface MutationGenqlSelection {
+    /**
+     * Get a presigned S3 URL for direct file upload.
+     * Rate limited to 30 requests per minute.
+     */
+    getPartnerUploadUrl?: (MediaAssetUploadUrlGenqlSelection & {
+        __args: {
+            filename: Scalars['String'];
+            fileExtension: Scalars['String'];
+        };
+    });
+    /**
+     * Record an uploaded media asset and link it to the partner's brand.
+     * Call after uploading to S3 via the presigned URL from getPartnerUploadUrl.
+     */
+    createPartnerMediaAsset?: (MediaAssetGenqlSelection & {
+        __args: {
+            mimetype: Scalars['String'];
+            filename: Scalars['String'];
+            dimensions: DimensionsInput;
+        };
+    });
+    /**
+     * Create a moment with optional venue and ticket tiers in one atomic operation.
+     * When type is IRL, the venue field is required.
+     */
+    createPartnerMoment?: (MomentGenqlSelection & {
+        __args: {
+            input: CreatePartnerMomentInput;
+        };
+    });
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 
 interface GraphqlOperation {
     query: string;
@@ -655,6 +820,9 @@ interface Client {
     query<R extends QueryGenqlSelection>(request: R & {
         __name?: string;
     }): Promise<FieldsSelection<Query, R>>;
+    mutation<R extends MutationGenqlSelection>(request: R & {
+        __name?: string;
+    }): Promise<FieldsSelection<Mutation, R>>;
 }
 declare const everything: {
     __scalar: boolean;
@@ -662,6 +830,9 @@ declare const everything: {
 declare const generateQueryOp: (fields: QueryGenqlSelection & {
     __name?: string;
 }) => GraphqlOperation;
+declare const generateMutationOp: (fields: MutationGenqlSelection & {
+    __name?: string;
+}) => GraphqlOperation;
 
 interface ITMPartnerClientConfig {
     /**
@@ -710,4 +881,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type Currency, type Dimensions, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type PartnerCustomer, type Payment, type PaymentStatus, type Query, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, createITMPartnerClient, everything, generateQueryOp };
+export { type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type Payment, type PaymentStatus, type Query, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };