feat(schema) support hook to poll triggers INT-15776

[casshill]

Add support for hook_to_poll style triggers (new schema)

• soft launch by hiding the doc references ie. this pr should not generate changes to the docs
• require performList and exclude perform.
  • Perform is a no-op for hook-to-poll triggers, the live Zap run calls performList (since it's essentially polling)
  • Should performSubscribe and performUnsubscribe be required? I think they are only optional for legacy hook support

[xavdid]

@casshill is this ready for review? It's still marked as draft, so I wasn't sure.

In any case, looks good! I'm not sure how much you care about hiding the new value from the docs, but we have some code for that in here:

zapier-platform/packages/schema/lib/utils/buildDocs.js

Lines 121 to 136 in e4cacfa

	if (_.get(property, 'docAnnotation.hide')) {
	return '';
	} else if (_.get(property, 'docAnnotation.required')) {
	// can also support keys besides "required"
	const annotation = property.docAnnotation.required;
	if (annotation.type === 'replace') {
	isRequired = annotation.value;
	} else if (annotation.type === 'append') {
	isRequired += annotation.value;
	} else {
	throw new Error(`unrecognized docAnnotation type: ${annotation.type}`);
	}
	}
	return `${quoteOrNa(key)} | ${isRequired} | ${typeOrLink(property)} | ${
	property.description || NO_DESCRIPTION
	}`;

We don't have anything for hiding a specific enum, but we could add it.

[casshill]

@casshill is this ready for review? It's still marked as draft, so I wasn't sure.

In any case, looks good! I'm not sure how much you care about hiding the new value from the docs, but we have some code for that in here:

zapier-platform/packages/schema/lib/utils/buildDocs.js

Lines 121 to 136 in e4cacfa

	if (_.get(property, 'docAnnotation.hide')) {
	return '';
	} else if (_.get(property, 'docAnnotation.required')) {
	// can also support keys besides "required"
	const annotation = property.docAnnotation.required;
	if (annotation.type === 'replace') {
	isRequired = annotation.value;
	} else if (annotation.type === 'append') {
	isRequired += annotation.value;
	} else {
	throw new Error(`unrecognized docAnnotation type: ${annotation.type}`);
	}
	}
	return `${quoteOrNa(key)} | ${isRequired} | ${typeOrLink(property)} | ${
	property.description || NO_DESCRIPTION
	}`;

We don't have anything for hiding a specific enum, but we could add it.

It's ready for feedback and suggestions :D
I thought I'd leave it as draft until we decided how/when we wanted to release it - thanks I'll take a look at the snippet you provided

[casshill]

@xavdid I couldn't see how to make the doc annotations hide for sub-components of a property, it seemed to be more for full property blocks?

Eg I don't think I can show docs for one enum value 'hook', but not for the second enum value 'hook_to_poll' (only for the whole enum property)

It might make more sense (added in the latest commit) to make a new operation schema, particular as we need to use performList instead of perform. What do you think of that as opposed to adding a new enum to the basic hook operation schema? I think we have the same issue with hiding the docs though. It's probably more subtle to just add an enum value if we don't want to publish the full docs though, so perhaps then enum is better for the soft launch and the new operation schema for the hard launch

[xavdid]

Right, there's not currently support for hiding a specific property. so we could add support for that, or do something different (such as a new schema).

If hook-to-poll doesn't have a perform at all, then I think it does make sense to have it as a new schema.

[xavdid]

Nice! this is looking good.

I haven't taken a super close look, but if you've done some testing then this should be safe enough! We'll want to push a test app to staging and actually make sure it all runs, but it should be pretty straightforward.