@codeqr/ts 0.24.1 → 0.25.0

package/src/resources/links/links.ts

@@ -26,63 +26,63 @@ export class Links extends APIResource {
   }
 
   /**
-   * Retrieve a paginated list of links for the authenticated workspace.
+   * Update a link for the authenticated workspace. If there's no change, returns it
+   * as it is.
    *
    * @example
    * ```ts
-   * const links = await client.links.list();
+   * const link = await client.links.update('linkId');
    * ```
    */
-  list(
-    query: LinkListParams | null | undefined = {},
+  update(
+    linkID: string,
+    body: LinkUpdateParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<LinkListResponse> {
-    return this._client.get('/links', { query, ...options });
+  ): APIPromise<Link> {
+    return this._client.put(path`/links/${linkID}`, { body, ...options });
   }
 
   /**
-   * Retrieve the info for a link.
+   * Retrieve a paginated list of links for the authenticated workspace.
    *
    * @example
    * ```ts
-   * const link = await client.links.retrieveInfo({
-   *   domain: 'x',
-   *   key: 'x',
-   *   projectSlug: 'x',
-   * });
+   * const links = await client.links.list();
    * ```
    */
-  retrieveInfo(query: LinkRetrieveInfoParams, options?: RequestOptions): APIPromise<Link> {
-    return this._client.get('/links/info', { query, ...options });
+  list(
+    query: LinkListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<LinkListResponse> {
+    return this._client.get('/links', { query, ...options });
   }
 
   /**
-   * Update a link for the authenticated workspace. If there's no change, returns it
-   * as it is.
+   * Delete a link for the authenticated workspace.
    *
    * @example
    * ```ts
-   * const link = await client.links.update('linkId');
+   * const link = await client.links.delete('linkId');
    * ```
    */
-  update(
-    linkID: string,
-    body: LinkUpdateParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<Link> {
-    return this._client.put(path`/links/${linkID}`, { body, ...options });
+  delete(linkID: string, options?: RequestOptions): APIPromise<LinkDeleteResponse> {
+    return this._client.delete(path`/links/${linkID}`, options);
   }
 
   /**
-   * Delete a link for the authenticated workspace.
+   * Retrieve the info for a link.
    *
    * @example
    * ```ts
-   * const link = await client.links.delete('linkId');
+   * const link = await client.links.retrieveInfo({
+   *   domain: 'x',
+   *   key: 'x',
+   *   projectSlug: 'x',
+   * });
    * ```
    */
-  delete(linkID: string, options?: RequestOptions): APIPromise<LinkDeleteResponse> {
-    return this._client.delete(path`/links/${linkID}`, options);
+  retrieveInfo(query: LinkRetrieveInfoParams, options?: RequestOptions): APIPromise<Link> {
+    return this._client.get('/links/info', { query, ...options });
   }
 }
 
@@ -98,7 +98,8 @@ export interface Link {
   android: string | null;
 
   /**
-   * Whether the short link is archived.
+   * Whether the short link is archived. Archiving hides it from the default
+   * dashboard listing; the link keeps redirecting and keeps counting clicks.
    */
   archived: boolean;
 
@@ -350,13 +351,35 @@ export interface Link {
 
 export namespace Link {
   export interface Rule {
-    attribute: 'device' | 'country' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'referrer' | 'language';
-
-    operator: 'equals' | 'not_equals';
+    attribute?:
+      | 'device'
+      | 'country'
+      | 'utm_source'
+      | 'utm_medium'
+      | 'utm_campaign'
+      | 'referrer'
+      | 'language'
+      | 'city'
+      | 'region'
+      | 'continent'
+      | 'utm_term'
+      | 'utm_content';
+
+    operator?: 'equals' | 'not_equals';
+
+    split?: Array<Rule.Split>;
+
+    url?: string;
+
+    value?: string;
+  }
 
-    url: string;
+  export namespace Rule {
+    export interface Split {
+      url: string;
 
-    value: string;
+      weight: number;
+    }
   }
 }
 
@@ -381,7 +404,8 @@ export interface LinkCreateParams {
   android?: string | null;
 
   /**
-   * Whether the short link is archived.
+   * Whether the short link is archived. Archiving hides it from the default
+   * dashboard listing; the link keeps redirecting and keeps counting clicks.
    */
   archived?: boolean;
 
@@ -524,6 +548,7 @@ export interface LinkCreateParams {
 
   /**
    * The unique name of the tags assigned to the short link (case insensitive).
+   * Ignored when `tagIds` is also present.
    */
   tagNames?: string | Array<string>;
 
@@ -1063,235 +1088,229 @@ export namespace LinkCreateParams {
   }
 
   export interface Rule {
-    attribute: 'device' | 'country' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'referrer' | 'language';
-
-    operator: 'equals' | 'not_equals';
+    attribute?:
+      | 'device'
+      | 'country'
+      | 'utm_source'
+      | 'utm_medium'
+      | 'utm_campaign'
+      | 'referrer'
+      | 'language'
+      | 'city'
+      | 'region'
+      | 'continent'
+      | 'utm_term'
+      | 'utm_content';
+
+    operator?: 'equals' | 'not_equals';
+
+    split?: Array<Rule.Split>;
+
+    url?: string;
+
+    value?: string;
+  }
 
-    url: string;
+  export namespace Rule {
+    export interface Split {
+      url: string;
 
-    value: string;
+      weight: number;
+    }
   }
 }
 
-export interface LinkListParams {
-  /**
-   * The Android device to filter by.
-   */
-  android?: string;
-
+export interface LinkUpdateParams {
   /**
-   * Maximum number of clicks
+   * The Android destination URL for the short link for Android device targeting.
    */
-  clicksMax?: number;
+  android?: string | null;
 
   /**
-   * Minimum number of clicks
+   * Whether the short link is archived. Archiving hides it from the default
+   * dashboard listing; the link keeps redirecting and keeps counting clicks.
    */
-  clicksMin?: number;
+  archived?: boolean;
 
   /**
-   * The comments to filter by.
+   * The comments for the short link.
    */
-  comments?: string;
+  comments?: string | null;
 
   /**
-   * Created after date (ISO string)
+   * The description of the short link generated via `api.codeqr.io/metatags`. Will
+   * be used for custom link preview if `proxy` is true.
    */
-  createdAfter?: string;
+  description?: string | null;
 
   /**
-   * Created before date (ISO string)
+   * Allow search engines to index your short link. Default is `false` if not
+   * provided. Learn more: https://codeqr.link/noindex
    */
-  createdBefore?: string;
+  doIndex?: boolean;
 
   /**
-   * The domain to filter the links. For example, `ac.me`. If not provided, all links
-   * of the project will be returned.
+   * The domain of the short link. If not provided, the main domain of the project
+   * will be used (or `codeqr.link` if the project has no domains).
    */
   domain?: string;
 
   /**
-   * Expires after date (ISO string)
+   * The URL to redirect to when the short link expires.
    */
-  expiresAfter?: string;
+  expiredUrl?: string | null;
 
   /**
-   * The date and time the short link will expire in ISO-8601 format. Must be in the
-   * future.
+   * The date and time when the short link will expire in ISO-8601 format. Must be in
+   * the future.
    */
   expiresAt?: string | null;
 
   /**
-   * Expires before date (ISO string)
-   */
-  expiresBefore?: string;
-
-  /**
-   * The folder ID to filter the links by.
-   */
-  folderId?: string;
-
-  /**
-   * Geographic segmentation information for the short link in JSON format
-   * `{[COUNTRY]: https://example.com }`.
-   */
-  geo?: LinkListParams.Geo | null;
-
-  /**
-   * Filter links that have comments (any comments)
+   * This is the ID of the link in your database. If set, it can be used to identify
+   * the link in the future. Must be prefixed with `ext_` when passed as a query
+   * parameter.
    */
-  hasComments?: boolean;
+  externalId?: string | null;
 
   /**
-   * Filter links that have custom social media cards
+   * Whether the short link is flexible.
    */
-  hasCustomSocial?: boolean;
+  flexible?: boolean;
 
   /**
-   * Filter links that have device targeting
+   * The unique ID existing folder to assign the short link to.
    */
-  hasDevice?: boolean;
+  folderId?: string | null;
 
   /**
-   * Filter links that have expiration date (any expiration)
+   * Geographic targeting information for the short link in JSON format
+   * `{[COUNTRY]: https://example.com }`.
    */
-  hasExpiration?: boolean;
+  geo?: LinkUpdateParams.Geo | null;
 
   /**
-   * Filter links that have geo-targeting
+   * The image of the short link generated via `api.codeqr.io/metatags`. Will be used
+   * for custom link preview if `proxy` is true.
    */
-  hasGeo?: boolean;
+  image?: string | null;
 
   /**
-   * Filter links that have password protection (any password)
+   * The iOS destination URL for the short link for iOS device targeting.
    */
-  hasPassword?: boolean;
+  ios?: string | null;
 
   /**
-   * Filter links that have tags (any tags)
+   * If the form is mandatory for the page.
    */
-  hasTags?: boolean;
+  isFormMandatory?: boolean;
 
   /**
-   * Filter links that have UTM parameters
+   * The slug of the short link. If not provided, a random 7-character slug will be
+   * generated.
    */
-  hasUTM?: boolean;
+  key?: string;
 
   /**
-   * The iOS device to filter by.
+   * The ID of the page to redirect to before the link destination.
    */
-  ios?: string;
+  pageId?: string | null;
 
   /**
-   * Link IDs to filter by.
+   * The URL of the page to redirect to before the link destination.
    */
-  linkIds?: string | Array<string>;
+  pageUrl?: string | null;
 
   /**
-   * The page number for pagination.
+   * The password required to access the short link destination URL.
    */
-  page?: number;
+  password?: string | null;
 
   /**
-   * The number of items per page.
+   * The prefix of the short link slug for randomly generated keys (for example, if
+   * the prefix is `/c/`, the generated keys will be in the format `/c/:key`). Will
+   * be ignored if `key` is provided.
    */
-  pageSize?: number;
+  prefix?: string;
 
   /**
-   * The password to filter by.
+   * Whether the short link has pre-redirection.
    */
-  password?: string;
+  preRedirection?: boolean;
 
   /**
-   * The slug of the project to which the link belongs. For example, for
-   * `app.codeqr.io/acme`, the projectSlug is `acme`.
+   * Whether the short link uses the custom link preview feature.
    */
-  projectSlug?: string;
+  proxy?: boolean;
 
   /**
-   * The search term to filter the links. The search term will be matched against the
-   * short link slug and the destination URL.
+   * Whether the short link statistics are publicly accessible.
    */
-  search?: string;
+  publicStats?: boolean;
 
   /**
-   * If should include archived links in the response. The default is `false` if not
-   * provided.
+   * Whether the short link uses link cloaking.
    */
-  showArchived?: boolean;
+  rewrite?: boolean;
 
   /**
-   * The field to sort the links by. The default is `createdAt`, and sort order is
-   * always descending.
+   * Smart rules for conditional destination routing by request attribute.
    */
-  sort?: 'createdAt' | 'clicks' | 'lastClicked';
+  rules?: Array<LinkUpdateParams.Rule> | null;
 
   /**
-   * @deprecated [OBSOLETO (use tagIds em vez disso)]: The unique ID of the tag
-   * assigned to the short link.
+   * @deprecated The unique ID of the tag assigned to the short link. This field is
+   * deprecated – use `tagIds` instead.
    */
-  tagId?: string;
+  tagId?: string | null;
 
   /**
-   * The IDs of the tags to filter the links.
+   * The unique IDs of the tags assigned to the short link.
    */
   tagIds?: string | Array<string>;
 
   /**
    * The unique name of the tags assigned to the short link (case insensitive).
+   * Ignored when `tagIds` is also present.
    */
   tagNames?: string | Array<string>;
 
   /**
-   * If should include links with conversion tracking enabled. The default is `false`
-   * if not provided.
-   */
-  trackConversion?: boolean;
-
-  /**
-   * Filter links marked as templates.
-   */
-  useAsTemplate?: boolean;
-
-  /**
-   * The ID of the user to filter by.
-   */
-  userId?: string;
-
-  /**
-   * Filter by UTM campaign value
+   * The title of the short link generated via `api.codeqr.io/metatags`. Will be used
+   * for custom link preview if `proxy` is true.
    */
-  utm_campaign?: string;
+  title?: string | null;
 
   /**
-   * Filter by UTM content value
+   * Whether to track conversions for the short link.
    */
-  utm_content?: string;
+  trackConversion?: boolean;
 
   /**
-   * Filter by UTM medium value
+   * The destination URL of the short link.
    */
-  utm_medium?: string;
+  url?: string;
 
   /**
-   * Filter by UTM source value
+   * Whether this link should be used as a reusable template.
    */
-  utm_source?: string;
+  useAsTemplate?: boolean;
 
   /**
-   * Filter by UTM term value
+   * The video of the short link.
    */
-  utm_term?: string;
+  video?: string | null;
 
   /**
-   * If should include tags in the response. The default is `false` if not provided.
+   * An array of webhook IDs to trigger when the link is clicked. These webhooks will
+   * receive click event data.
    */
-  withTags?: boolean;
+  webhookIds?: Array<string> | null;
 }
 
-export namespace LinkListParams {
+export namespace LinkUpdateParams {
   /**
-   * Geographic segmentation information for the short link in JSON format
+   * Geographic targeting information for the short link in JSON format
    * `{[COUNTRY]: https://example.com }`.
    */
   export interface Geo {
@@ -1795,184 +1814,201 @@ export namespace LinkListParams {
 
     ZW?: string;
   }
-}
 
-export interface LinkRetrieveInfoParams {
-  /**
-   * The domain of the link to be retrieved. For example, for `codeqr.link/github`,
-   * the domain is `codeqr.link`.
-   */
-  domain: string;
+  export interface Rule {
+    attribute?:
+      | 'device'
+      | 'country'
+      | 'utm_source'
+      | 'utm_medium'
+      | 'utm_campaign'
+      | 'referrer'
+      | 'language'
+      | 'city'
+      | 'region'
+      | 'continent'
+      | 'utm_term'
+      | 'utm_content';
+
+    operator?: 'equals' | 'not_equals';
+
+    split?: Array<Rule.Split>;
+
+    url?: string;
+
+    value?: string;
+  }
 
+  export namespace Rule {
+    export interface Split {
+      url: string;
+
+      weight: number;
+    }
+  }
+}
+
+export interface LinkListParams {
   /**
-   * The key of the link to be retrieved. For example, for `codeqr.link/github`, the
-   * key is `github`.
+   * The Android device to filter by.
    */
-  key: string;
+  android?: string;
 
   /**
-   * The slug of the project to which the link belongs. For example, for
-   * `app.codeqr.io/acme`, the projectSlug is `acme`.
+   * Maximum number of clicks
    */
-  projectSlug: string;
+  clicksMax?: number;
 
   /**
-   * This is the ID of the link in your database. Must be prefixed with `ext_` when
-   * passed as a query parameter.
+   * Minimum number of clicks
    */
-  externalId?: string;
+  clicksMin?: number;
 
   /**
-   * The unique ID of the short link.
+   * The comments to filter by.
    */
-  linkId?: string;
-}
+  comments?: string;
 
-export interface LinkUpdateParams {
   /**
-   * The Android destination URL for the short link for Android device targeting.
+   * Created after date (ISO string)
    */
-  android?: string | null;
+  createdAfter?: string;
 
   /**
-   * Whether the short link is archived.
+   * Created before date (ISO string)
    */
-  archived?: boolean;
+  createdBefore?: string;
 
   /**
-   * The comments for the short link.
+   * The domain to filter the links. For example, `ac.me`. If not provided, all links
+   * of the project will be returned.
    */
-  comments?: string | null;
+  domain?: string;
 
   /**
-   * The description of the short link generated via `api.codeqr.io/metatags`. Will
-   * be used for custom link preview if `proxy` is true.
+   * Expires after date (ISO string)
    */
-  description?: string | null;
+  expiresAfter?: string;
 
   /**
-   * Allow search engines to index your short link. Default is `false` if not
-   * provided. Learn more: https://codeqr.link/noindex
+   * The date and time the short link will expire in ISO-8601 format. Must be in the
+   * future.
    */
-  doIndex?: boolean;
+  expiresAt?: string | null;
 
   /**
-   * The domain of the short link. If not provided, the main domain of the project
-   * will be used (or `codeqr.link` if the project has no domains).
+   * Expires before date (ISO string)
    */
-  domain?: string;
+  expiresBefore?: string;
 
   /**
-   * The URL to redirect to when the short link expires.
+   * The folder ID to filter the links by.
    */
-  expiredUrl?: string | null;
+  folderId?: string;
 
   /**
-   * The date and time when the short link will expire in ISO-8601 format. Must be in
-   * the future.
+   * Geographic segmentation information for the short link in JSON format
+   * `{[COUNTRY]: https://example.com }`.
    */
-  expiresAt?: string | null;
+  geo?: LinkListParams.Geo | null;
 
   /**
-   * This is the ID of the link in your database. If set, it can be used to identify
-   * the link in the future. Must be prefixed with `ext_` when passed as a query
-   * parameter.
+   * Filter links that have comments (any comments)
    */
-  externalId?: string | null;
+  hasComments?: boolean;
 
   /**
-   * Whether the short link is flexible.
+   * Filter links that have custom social media cards
    */
-  flexible?: boolean;
+  hasCustomSocial?: boolean;
 
   /**
-   * The unique ID existing folder to assign the short link to.
+   * Filter links that have device targeting
    */
-  folderId?: string | null;
+  hasDevice?: boolean;
 
   /**
-   * Geographic targeting information for the short link in JSON format
-   * `{[COUNTRY]: https://example.com }`.
+   * Filter links that have expiration date (any expiration)
    */
-  geo?: LinkUpdateParams.Geo | null;
+  hasExpiration?: boolean;
 
   /**
-   * The image of the short link generated via `api.codeqr.io/metatags`. Will be used
-   * for custom link preview if `proxy` is true.
+   * Filter links that have geo-targeting
    */
-  image?: string | null;
+  hasGeo?: boolean;
 
   /**
-   * The iOS destination URL for the short link for iOS device targeting.
+   * Filter links that have password protection (any password)
    */
-  ios?: string | null;
+  hasPassword?: boolean;
 
   /**
-   * If the form is mandatory for the page.
+   * Filter links that have tags (any tags)
    */
-  isFormMandatory?: boolean;
+  hasTags?: boolean;
 
   /**
-   * The slug of the short link. If not provided, a random 7-character slug will be
-   * generated.
+   * Filter links that have UTM parameters
    */
-  key?: string;
+  hasUTM?: boolean;
 
   /**
-   * The ID of the page to redirect to before the link destination.
+   * The iOS device to filter by.
    */
-  pageId?: string | null;
+  ios?: string;
 
   /**
-   * The URL of the page to redirect to before the link destination.
+   * Link IDs to filter by.
    */
-  pageUrl?: string | null;
+  linkIds?: string | Array<string>;
 
   /**
-   * The password required to access the short link destination URL.
+   * The page number for pagination.
    */
-  password?: string | null;
+  page?: number;
 
   /**
-   * The prefix of the short link slug for randomly generated keys (for example, if
-   * the prefix is `/c/`, the generated keys will be in the format `/c/:key`). Will
-   * be ignored if `key` is provided.
+   * The number of items per page.
    */
-  prefix?: string;
+  pageSize?: number;
 
   /**
-   * Whether the short link has pre-redirection.
+   * The password to filter by.
    */
-  preRedirection?: boolean;
+  password?: string;
 
   /**
-   * Whether the short link uses the custom link preview feature.
+   * The slug of the project to which the link belongs. For example, for
+   * `app.codeqr.io/acme`, the projectSlug is `acme`.
    */
-  proxy?: boolean;
+  projectSlug?: string;
 
   /**
-   * Whether the short link statistics are publicly accessible.
+   * The search term to filter the links. The search term will be matched against the
+   * short link slug and the destination URL.
    */
-  publicStats?: boolean;
+  search?: string;
 
   /**
-   * Whether the short link uses link cloaking.
+   * If should include archived links in the response. The default is `false` if not
+   * provided.
    */
-  rewrite?: boolean;
+  showArchived?: boolean;
 
   /**
-   * Smart rules for conditional destination routing by request attribute.
+   * The field to sort the links by. The default is `createdAt`, and sort order is
+   * always descending.
    */
-  rules?: Array<LinkUpdateParams.Rule> | null;
+  sort?: 'createdAt' | 'clicks' | 'lastClicked';
 
   /**
-   * @deprecated The unique ID of the tag assigned to the short link. This field is
-   * deprecated – use `tagIds` instead.
+   * @deprecated [OBSOLETO (use tagIds em vez disso)]: The unique ID of the tag
+   * assigned to the short link.
    */
-  tagId?: string | null;
+  tagId?: string;
 
   /**
-   * The unique IDs of the tags assigned to the short link.
+   * The IDs of the tags to filter the links.
    */
   tagIds?: string | Array<string>;
 
@@ -1982,41 +2018,55 @@ export interface LinkUpdateParams {
   tagNames?: string | Array<string>;
 
   /**
-   * The title of the short link generated via `api.codeqr.io/metatags`. Will be used
-   * for custom link preview if `proxy` is true.
+   * If should include links with conversion tracking enabled. The default is `false`
+   * if not provided.
    */
-  title?: string | null;
+  trackConversion?: boolean;
 
   /**
-   * Whether to track conversions for the short link.
+   * Filter links marked as templates.
    */
-  trackConversion?: boolean;
+  useAsTemplate?: boolean;
 
   /**
-   * The destination URL of the short link.
+   * The ID of the user to filter by.
    */
-  url?: string;
+  userId?: string;
 
   /**
-   * Whether this link should be used as a reusable template.
+   * Filter by UTM campaign value
    */
-  useAsTemplate?: boolean;
+  utm_campaign?: string;
 
   /**
-   * The video of the short link.
+   * Filter by UTM content value
    */
-  video?: string | null;
+  utm_content?: string;
 
   /**
-   * An array of webhook IDs to trigger when the link is clicked. These webhooks will
-   * receive click event data.
+   * Filter by UTM medium value
    */
-  webhookIds?: Array<string> | null;
+  utm_medium?: string;
+
+  /**
+   * Filter by UTM source value
+   */
+  utm_source?: string;
+
+  /**
+   * Filter by UTM term value
+   */
+  utm_term?: string;
+
+  /**
+   * If should include tags in the response. The default is `false` if not provided.
+   */
+  withTags?: boolean;
 }
 
-export namespace LinkUpdateParams {
+export namespace LinkListParams {
   /**
-   * Geographic targeting information for the short link in JSON format
+   * Geographic segmentation information for the short link in JSON format
    * `{[COUNTRY]: https://example.com }`.
    */
   export interface Geo {
@@ -2520,16 +2570,37 @@ export namespace LinkUpdateParams {
 
     ZW?: string;
   }
+}
 
-  export interface Rule {
-    attribute: 'device' | 'country' | 'utm_source' | 'utm_medium' | 'utm_campaign' | 'referrer' | 'language';
+export interface LinkRetrieveInfoParams {
+  /**
+   * The domain of the link to be retrieved. For example, for `codeqr.link/github`,
+   * the domain is `codeqr.link`.
+   */
+  domain: string;
 
-    operator: 'equals' | 'not_equals';
+  /**
+   * The key of the link to be retrieved. For example, for `codeqr.link/github`, the
+   * key is `github`.
+   */
+  key: string;
+
+  /**
+   * The slug of the project to which the link belongs. For example, for
+   * `app.codeqr.io/acme`, the projectSlug is `acme`.
+   */
+  projectSlug: string;
 
-    url: string;
+  /**
+   * This is the ID of the link in your database. Must be prefixed with `ext_` when
+   * passed as a query parameter.
+   */
+  externalId?: string;
 
-    value: string;
-  }
+  /**
+   * The unique ID of the short link.
+   */
+  linkId?: string;
 }
 
 Links.Bulk = Bulk;
@@ -2540,9 +2611,9 @@ export declare namespace Links {
     type LinkListResponse as LinkListResponse,
     type LinkDeleteResponse as LinkDeleteResponse,
     type LinkCreateParams as LinkCreateParams,
+    type LinkUpdateParams as LinkUpdateParams,
     type LinkListParams as LinkListParams,
     type LinkRetrieveInfoParams as LinkRetrieveInfoParams,
-    type LinkUpdateParams as LinkUpdateParams,
   };
 
   export {