feat(web-api): add slackLists methods

[srtaalej]

Summary

This PR adds the following slackLists methods to the slack_sdk: access.delete, access.set, create, download.get, download.start, items.create, items.delete, items.deleteMultiple, items.info, items.list, items.update, update

Testing

const list = await app.client.slacklists.create( { name: "backlog" } )

Requirements (place an x in each [ ])

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.09%. Comparing base (8da8e09) to head (1391ed1).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2421      +/-   ##
==========================================
+ Coverage   93.02%   93.09%   +0.06%     
==========================================
  Files          40       40              
  Lines       11127    11238     +111     
  Branches      713      713              
==========================================
+ Hits        10351    10462     +111     
  Misses        764      764              
  Partials       12       12              

Flag	Coverage Δ
cli-hooks	95.23% <ø> (ø)
cli-test	94.79% <ø> (ø)
oauth	77.39% <ø> (ø)
socket-mode	61.87% <ø> (ø)
web-api	98.11% <100.00%> (+0.03%)	⬆️
webhook	96.66% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[zimeg]

@srtaalej Exciting times for these methods I think! 📝

I left a few findings to match adjacent implementations and more thoughts on typing here. We might want to discuss how schemas are handled since I believe developers will want to import these for use elsewhere.

So open to your thoughts on this, and I look forward to continued testing 🧪 ✨

[zimeg]

🔏 note: Let's revisit these responses after a java implementation has been released!

[zimeg]

🚧 issue: Not having all response types can cause issues with typescript checks. We'll want to revisit these outputs with automated response generation soon since I notice some missing values in these types:

• list_id: String
• list_metadata: Object

{"ok":true,"list_id":"F09ULKZ15TJ","list_metadata":{"schema":[{"key":"task_name","name":"Task Name","is_primary_column":true,"type":"text","id":"Col09U582EPS5"},{"key":"due_date","name":"Due Date","is_primary_column":false,"type":"date","id":"Col09TKUQDVJ7"},{"key":"status","name":"Status","is_primary_column":false,"type":"select","options":{"choices":[{"value":"not_started","label":"Not Started","color":"red"},{"value":"in_progress","label":"In Progress","color":"yellow"},{"value":"completed","label":"Completed","color":"green"}],"show_member_name":true},"id":"Col09TNT4AX0V"},{"key":"assignee","name":"Assignee","is_primary_column":false,"type":"user","id":"Col09TAT5Q3ST"}],"subtask_schema":[{"key":"task_name","name":"Task Name","is_primary_column":true,"type":"text","id":"Col09U582EPS5"}]}}

[zimeg]

@srtaalej Sweeeeet! This is a nice changeset in the works ⚙️ ✨

I'm requesting a few changes before this merges, with a focus on some of the following:

• JSdoc for method arguments
• Response shapes from the API
• Examples in testing

Overall things are solid but the last point makes me wonder more if introducing a schema now is meaningful... Let me know if I can add more detail or help otherwise!

[zimeg]

🧪 Testing steps - similar to slackapi/python-slack-sdk#1772!

const listCreateResponse = await app.client.slackLists.create({
  name: "Test List - SlackLists API",
  description_blocks: [
    {
      type: "rich_text",
      elements: [
        {
          type: "rich_text_section",
          elements: [
            { type: "text", text: "List to keep track of tasks!" }
          ]
        }
      ]
    }
  ],
  schema: [
    {
      key: "task_name",
      name: "Task Name",
      type: "text",
      is_primary_column: true,
    },
    {
      key: "due_date",
      name: "Due Date",
      type: "date",
    },
    {
      key: "status",
      name: "Status",
      type: "select",
      options: {
        choices: [
          { value: "not_started", label: "Not Started", color: "red" },
          { value: "in_progress", label: "In Progress", color: "yellow" },
          { value: "completed", label: "Completed", color: "green" },
        ],
      },
    },
    {
      key: "assignee",
      name: "Assignee",
      type: "user",
    },
  ],
});

// extract fields
const keyToId = Object.fromEntries(
  listCreateResponse.list_metadata.schema.map(col => [col.key, col.id])
);

const taskNameColId = keyToId["task_name"];
const listId = listCreateResponse.list_id;

// -----------------------
// Set access permissions
// -----------------------
await app.client.slackLists.access.set({
  list_id: listId,
  access_level: "write",
  user_ids: ["U04051AF9NJ"],
});

// -----------------------
// Create list items
// -----------------------
const itemResponse1 = await app.client.slackLists.items.create({
  list_id: listId,
  initial_fields: [
    {
      column_id: taskNameColId,
      rich_text: [
        {
          type: "rich_text",
          elements: [
            {
              type: "rich_text_section",
              elements: [{ type: "text", text: "CLI app unlink command" }],
            },
          ],
        },
      ],
    },
  ],
});

// four empty items
const itemResponse2 = await app.client.slackLists.items.create({ list_id: listId });
const itemResponse3 = await app.client.slackLists.items.create({ list_id: listId });
const itemResponse4 = await app.client.slackLists.items.create({ list_id: listId });
const itemResponse5 = await app.client.slackLists.items.create({ list_id: listId });

const itemId1 = itemResponse1.item.id;
const itemId2 = itemResponse2.item.id;
const itemId3 = itemResponse3.item.id;
const itemId4 = itemResponse4.item.id;
const itemId5 = itemResponse5.item.id;

// -----------------------
// Delete items
// -----------------------
await app.client.slackLists.items.delete({
  list_id: listId,
  id: itemId3,
});

await app.client.slackLists.items.deleteMultiple({
  list_id: listId,
  ids: [itemId4, itemId5],
});

// -----------------------
// Retrieve a single item
// -----------------------
const itemInfo = await app.client.slackLists.items.info({
  list_id: listId,
  id: itemId1,
  include_is_subscribed: true,
});

// -----------------------
// Retrieve all items
// -----------------------
const itemsList = await app.client.slackLists.items.list({
  list_id: listId,
  limit: 50,
  archived: false,
});

// -----------------------
// Download full list data
// -----------------------
const downloadStart = await app.client.slackLists.download.start({
  list_id: listId,
  include_archived: false,
});

const downloadGet = await app.client.slackLists.download.get({
  list_id: listId,
  job_id: downloadStart.job_id,
});

// -----------------------
// Update a list item
// -----------------------
await app.client.slackLists.items.update({
  list_id: listId,
  cells: [
    {
      column_id: taskNameColId,
      row_id: itemId1,
      rich_text: [
        {
          type: "rich_text",
          elements: [
            {
              type: "rich_text_section",
              elements: [{ type: "text", text: "Updated text" }],
            },
          ],
        },
      ],
    },
  ],
});

// -----------------------
// Update list metadata
// -----------------------
await app.client.slackLists.update({
  id: listId,
  name: "Test List - UPDATED",
  description_blocks: [
    {
      type: "rich_text",
      elements: [
        {
          type: "rich_text_section",
          elements: [
            { type: "text", text: "This list has been updated via API" },
          ],
        },
      ],
    },
  ],
  todo_mode: false,
});

// -----------------------
// Remove access
// -----------------------
await app.client.slackLists.access.delete({
  list_id: listId,
  user_ids: ["U04051AF9NJ"],
});

console.log("Done!");

[zimeg]

@srtaalej Thanks for making these changes all the more! 📜 🎉

I noticed a few small findings around testing IDs still and I hold caution to incomplete response types, but I don't believe that's blocking.

Let me know what you think about the response types though! I notice solid progress with slackapi/java-slack-sdk#1537 that we can perhaps wait for?

[zimeg]

Suggested change

	list_id: 'L1234567890',
	ids: ['I1234567890', 'I0987654321'],
	list_id: 'F1234567890',
	ids: ['Fe1234567890', 'Fe0987654321'],

👁️‍🗨️ quibble: I'm missing other suggestions in this file, but these IDs might have unexpected prefixes-

[zimeg]

🧮 quibble(non-blocking): Ordering this to match method implementations above can be nice too!

[zimeg]

🚧 issue: Not having all response types can cause issues with typescript checks. We'll want to revisit these outputs with automated response generation soon since I notice some missing values in these types:

• list_id: String
• list_metadata: Object

{"ok":true,"list_id":"F09ULKZ15TJ","list_metadata":{"schema":[{"key":"task_name","name":"Task Name","is_primary_column":true,"type":"text","id":"Col09U582EPS5"},{"key":"due_date","name":"Due Date","is_primary_column":false,"type":"date","id":"Col09TKUQDVJ7"},{"key":"status","name":"Status","is_primary_column":false,"type":"select","options":{"choices":[{"value":"not_started","label":"Not Started","color":"red"},{"value":"in_progress","label":"In Progress","color":"yellow"},{"value":"completed","label":"Completed","color":"green"}],"show_member_name":true},"id":"Col09TNT4AX0V"},{"key":"assignee","name":"Assignee","is_primary_column":false,"type":"user","id":"Col09TAT5Q3ST"}],"subtask_schema":[{"key":"task_name","name":"Task Name","is_primary_column":true,"type":"text","id":"Col09U582EPS5"}]}}